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:

KeywordMeaningMandatory
FILENAMEFile name of the file to be usedyes
FILETYPEFix text that describes the type of the fileyes
MD5SUMMD5 checksum for verifying the integrity of the fileyes
FILESIZEIndication of the file size in bytesNo
DESCRIPTIONFree text that describes the file to be usedNo
VERSIONA version designationfor each FILETYPE marked with an * in the table below
REQUIRED_SWDefines the firmware version that must be presentfor FILETYPE "Incremental Software Update"
KEYdefines 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:

FILETYPEMeaning
Full Software UpdateThe file is a major update (1.0, 2.0, 3.0 etc.). *
Incremental Software UpdateThe file is a minor update (2.1, 2.2, 2.2 etc.). *
Binary ConfigurationThe file is a profile in form of a binary file.
ASCII ConfigurationThe file is an ASCII configuration that will immediately be executed and not stored upon uploading.
Stored ASCII ConfigurationThe file is an ASCII configuration that will be stored and not executed upon uploading.
OpenVPN ConfigurationThe file is an OpenVPN configuration file (.ovpn), which will be translated into the internal OpenVPN configuration upon uploading.
ContainerThe file is a Linux container.
LicenceThe file is a licence that unlocks the functionality within a container.
Container ConfigurationThe file is the content of /data/etc of a container packed as tar archive.
Full StorageThe file is a collection of files packed as a tar archive for container storage; already existing folders will be deleted before uploading.
Incremental StorageThe file is a collection of files packed as a tar archive for container storage; only already existing files will be overwritten during uploading.
BootloaderThe file is the bootloader that loads the firmware onto the rooter. *
RescuefsThe file is a minimal operating system that permits to restore the firmware on the router following a secure decommissioning with erasing the memory. *
OEM BrandingThe file contains individual default settings.
DSL Firmware UpdateThe 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 private key for signing the package must not be stored on the device. Different key pairs must be used for signing and encrypting. The reason for this is that the private key for decryption is stored on the device and one of the many field devices is easier to compromise than a computer in the control center. Therefore, the private key stored on the device for decryption will not be trusted for signing any more. An encryption without signing is not supported since no authentication has taken place here and the additional effort for the additional signing is marginal.

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

Back to overview