Securing a configuration

The TomTom Bridge has the option to digitally sign your configuration, making sure no tampered configurations can be installed onto your devices. It requires a list of keys for the device and signature files for update-locations and all package-lists. The signature files are RSA keys that have been hashed using sha256, and have a .sig extension.

To generate these keys you need an SSL key generator like openssl.

1# Create a private key. The des3 option will force using a pass phrase.
2openssl genrsa -des3 -out privatekey.pem 1024
3# Extract the public key.
4openssl rsa -in privatekey.pem -pubout -outform DER -out publickey.der

Using the generated private key, you can proceed to sign your files like this:

# Sign a file.
openssl dgst -sha256 -sign privatekey.pem -out update-locations.sig update-locations

The verification process starts with the public device key file. It is used to verify if the list of public keys supplied by you is valid. The only way to get this key on the device currently is to ask us to create a ttpkg file with your key. This is because the key is stored in an area where other apps cannot write.

The key file is on the device stored at /data/ttcontent/common/installed/keys/device-key/device.key

Please contact us through your existing contact or via the Contact us page if you need this functionality and you want to get the device.key file installed on your devices.

The update process requires a list of keys to verify any signatures it encounters. The device key is used to verify that this list has not been tampered with. Once it passes this check, the key list is used to check all other signature files with. The key list file is named verification-public-keys and has the following content:

1{
2  "schema": "1",
3  "keys": [
4    { "filename": "tomtom-public.key", "hash": "<hash of key-file>" },
5    { "filename": "customer.key", "hash": "<hash of key-file>" }
6  ]
7}

The hashes are sha256 hashes of the mentioned files. When a key list is valid, it is copied onto the device for future reference.

So how do you inform the "Software update" application where to find all this information? Well, in two parts. First there's the signature files that are placed next to the file they are signing. The second part is the location of the key list and the keys it defines. Let's look at an example SD card/USB attached storage layout:

How are they all used? Well, first, the process checks if a device.key is present on the device. If so, it will verify the signature of the verification-public-keys with it. If that passes, the update-locations file is verified against any of the public keys. If that passes, each package-list is verified against the public keys as well. Only if they all pass will updating the device truly start.

If any of these steps fail, the update will not proceed. There is one exception. If there is no device.key file on the device, the keys will be deemed irrelevant and the update will proceed _ without any verification_ against those keys!