 |
Online Help |
Update packets
General Information
Update packets are used to exchange files with the router that are to be stored or executed on the router. Each update packet contains a manifest in form of a file; the entries in this file describe the data contained. The manifest and the files as uncompressed tar archive together form an update packet. The files can be firmware or configuration files or also containers.
Already packed packets (those already contain a MANIFEST) can already be used for an update. If different update packets are to be combined, for example a container packet and an ASCII configuration (as in below example), the individual packets must be unpacked first and then bundled to a common update packet together with the manifest.
If the integrity of an update packet must be assured particularly, it is also possible to sign it or encrypt and sign it. It can also be enforced that the router only accepts signed packets.
Manifest
The manifest is a text file (ASCII or UTF-8 without BOM) with the file name "MANIFEST" (without file name extension, e.g. .txt). It contains sections that describe the files in the archive. Empty lines are ignored. Capitalization is not ignored. Each line must start with a keyword which is followed by the "=” character and the value. No blanks are permitted directly before and after the "=".
The order of the sections in the manifest determines the order of processing in the router. A container needs to be installed first, before it can be started by its configuration for example.
A new section starts with the keyword "FILENAME". The manifest should always be the first file that is contained in the archive. Thus, an update packet does not have to be transmitted completely to be able to see what this archive contains. Keywords contained in the manifest are:
| Keyword | Meaning | Mandatory |
|---|---|---|
| FILENAME | File name of the file to be used | yes |
| FILETYPE | Fix text that describes the type of the file | yes |
| MD5SUM | MD5 checksum for verifying the integrity of the file | yes |
| FILESIZE | Indication of the file size in bytes | No |
| DESCRIPTION | Free text that describes the file to be used | No |
| VERSION | A version designation | for each FILETYPE marked with an * in the table below |
| REQUIRED_SW | Defines the firmware version that must be present | for FILETYPE "Incremental Software Update" |
| KEY | defines the description of the key that must be contained in the profile to be able to unpack an encrypted container. The appropriate public key will be used automatically. | No |
Possible entries for FILETYPE are:
| FILETYPE | Meaning |
|---|---|
| Full Software Update | The file is a major update (1.0, 2.0, 3.0 etc.). * |
| Incremental Software Update | The file is a minor update (2.1, 2.2, 2.2 etc.). * |
| Binary Configuration | The file is a profile in form of a binary file. |
| ASCII Configuration | The file is an ASCII configuration that will immediately be executed and not stored upon uploading. |
| Stored ASCII Configuration | The file is an ASCII configuration that will be stored and not executed upon uploading. |
| OpenVPN Configuration | The file is an OpenVPN configuration file (.ovpn), which will be translated into the internal OpenVPN configuration upon uploading. |
| Container | The file is a Linux container. |
| Licence | The file is a licence that unlocks the functionality within a container. |
| Container Configuration | The file is the content of /data/etc of a container packed as tar archive. |
| Full Storage | The file is a collection of files packed as a tar archive for container storage; already existing folders will be deleted before uploading. |
| Incremental Storage | The file is a collection of files packed as a tar archive for container storage; only already existing files will be overwritten during uploading. |
| Bootloader | The file is the bootloader that loads the firmware onto the rooter. * |
| Rescuefs | The file is a minimal operating system that permits to restore the firmware on the router following a secure decommissioning with erasing the memory. * |
| OEM Branding | The file contains individual default settings. |
| DSL Firmware Update | The file contains a firmware for the DSL modem. * |
Example of a manifest for a firmware packet
FILENAME=update-2.0-to-2.1.bin
DESCRIPTION=Firmware
FILESIZE=1317296
MD5SUM=9f660c9f8420877bc13ee3b58fe5de35
FILETYPE=Incremental Software Update
VERSION=2.1
REQUIRED_SW=2.0
Example of a manifest for a profile packet
FILENAME=Profile
FILESIZE=17312
FILETYPE=Binary Configuration
DESCRIPTION=Profile: 'Profile', created on 2016-05-20 12:42:40
MD5SUM=3750def5c933925710196ae756cda1eb
Example of a manifest for an ASCII configuration packet
FILENAME=ascii.txt
DESCRIPTION=ASCII config
MD5SUM=11d11f5bd994e6ad1294e14fe921de5f
FILETYPE=ASCII Configuration
Example of a manifest for a container packet
FILENAME=container_b334b401.tar.xz
DESCRIPTION=Container: 'container_b334b401', created on 2016-05-19 15:33:37
FILETYPE=Container
FILESIZE=1482168
MD5SUM=83b7e8d4dd10d07476e68b315c74ee2d
Example of a manifest for a container configuration packet
FILENAME=etc_container_b334b401
FILESIZE=346368
FILETYPE=Container configuration
DESCRIPTION=Configuration of container: 'container_b334b401'
MD5SUM=3bf7c35af8fe9bf5170ab10207953097
Example of a manifest for a licence packet
FILENAME=Application_Name
FILESIZE=1368
FILETYPE=Licence
DESCRIPTION=Activate feature set X'
MD5SUM=864333cf5977c2d3c9de99365516a073
Example of a manifest for an incremental container storage packet
FILENAME=containers_inc.tar.gz
DESCRIPTION=Storage
FILESIZE=290
FILETYPE=Incremental Storage
MD5SUM=63b77afc746cee94a5cfe604ad1efe5a
Example of a manifest for a packet with a container and an ASCII configuration
FILENAME=container_b334b401.tar.xz
DESCRIPTION=Container: 'container_b334b401', created on 2016-05-19 15:33:37
FILETYPE=Container
FILESIZE=1482168
MD5SUM=83b7e8d4dd10d07476e68b315c74ee2d
FILENAME=ascii.txt
DESCRIPTION=ASCII config
MD5SUM=11d11f5bd994e6ad1294e14fe921de5f
FILETYPE=ASCII Configuration
Signing and encrypting an update packet
This Configuration Guide describes how to proceed for signing and encrypting update packages.
In order to sign or encrypt and sign an update packet in PKCS#7 format, a distinct Public Key Infrastructure (PKI) is required. The certificate for encryption must have set the key usage (Key Usage) “Data Encipherment” and the certificate for the signature “Digital Signature”. Certificates or CRLs that can be attached when encrypting and/or signing the packet in PKCS#7 format will be ignored.
In order to verify/decrypt the packets, the following certificates and keys of the PKI must be uploaded to the router in the Administration menu on the Certificates page.
- CA certificate on which the PKI is based
- Certificate for encrypting the packet
- Private key for encrypting the packet
- Certificate for signing the packet
The system time (date) of the router must be within the validity period of the certificates.
Packets must first be encrypted before signing the encrypted packet.
If an unencrypted packet is to be signed only, the file name extensions listed below must be modified.
Encrypting and signing take place using openssl cms with the following command calls:
Encrypting
openssl cms -encrypt -aes-256-cbc -in upacket.tar -binary -outform DER -out upacket.tar.enc crypt.crt
Signing
openssl cms -sign -nocerts -md sha256 -in upacket.tar.enc -nodetach -binary -signer trust.crt -inkey trust.pem -out upacket.tar.enc.sign -outform DER
The following command calls can be used for test purposes:
Verifying
openssl cms -verify -CAfile CA.crt -certfile trust.crt -in upacket.tar.enc.sign -inform DER -out upacket.tar.enc
Decrypting
openssl cms -decrypt -recip crypt.crt -in upacket.tar.enc -inkey crypt.pem -inform DER -out upacket.tar
Removing signature without verification
openssl cms -verify -noverify -in upacket.tar.sign -inform DER -out upacket.tar
The following applies:
upacket.tar: File name of the update packet to be signed/encrypted
upacket.tar.enc: File name of the encrypted update packet
upacket.tar.enc.sign: File name of the update packet to be encrypted and signed
crypt.crt: Certificate for encrypting the packet
crypt.pem: Private key for encrypting the packet
trust.crt: Certificate for signing the packet
trust.pem: Private key for signing the packet