|
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 "=".
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 | yes |
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 |
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 |
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 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
This Configuration Guide describes how to proceed for signing and encrypting update packets.
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 extension (Key Usage) "Data Encipherment" and the certificate for the signature "Digital Signature".
Certificates or CRLs contained in the encrypted and/or signed packet 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 packet 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 packets is to be singed only, below file name extensions need to 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
|