Is this page helpful?

Offline Signing Keys

Introduction

In this article, you will learn how to leverage the security features of the Torizon Cloud by using offline software signing keys.

Why Use Offline Software Signing Keys

Torizon Cloud uses public key cryptography to sign metadata about all the software in your repository. When you first create an account on the platform, the Torizon Cloud generates a complete set of keys for you, stores them securely, and signs any software you upload using these keys. This setup lets you get started using Torizon Cloud quickly, without having to deal with managing your signing keys.

However, this initial configuration has a downside: it makes your Torizon Cloud account a potential single point of failure. If your Torizon Cloud account has been compromised and your signing keys are online, the attacker would be able to upload malicious software to the platform, and then order your devices to install it. For this reason, we recommend taking your software signing keys offline for serious production deployments. This creates a separation of responsibility, so that the authority for signing software and the authority for ordering devices to install updates are not kept in the same place. This is one of the key security benefits of using Torizon OTA Updates: once your keys are taken offline, your devices remain safe from malicious software updates even if there is a serious breach, like a phishing attack that manages to steal your login credentials.

How to use Offline Software Signing Keys

When starting with the Torizon default configuration, you use the online-maintained keys automatically while creating a package using the Torizon Cloud Web UI. When using TorizonCore Builder to push packages to the Torizon Cloud, you also use the online-maintained keys in a packed format--the credentials.zip file--which is the format that TorizonCore Builder requires for many commands.

To actually use offline keys for signing your Torizon OTA Updates, you will need to perform two actions:

• Rotate the keys offline.
• Pack the offline signing keys into the new credentials.zip file that will be used to push packages to the Torizon Cloud.

These two procedures will be explained in detail further down in this article.

Disclaimer

• Once you take your root keys offline, they are your responsibility. If you lose them, Toradex cannot recover them for you. We strongly recommend creating a practice repo to play around with, especially if you are using more advanced features like key thresholds or external signers. Only take your keys offline in your production repository once you are confident you know what you’re doing.

• Once your keys are offline, you will lose the ability to take certain actions via the web UI, including uploading new software and deleting or modifying old software. Instead, these will need to be done with your offline key using uptane-sign or torizoncore-builder.

• All Uptane metadata has an expiry date. When your keys are online, the Torizon Cloud automatically take care of renewing all your metadata before it expires. Once you take your keys offline, we will no longer be able to do that for you. Make sure you have a plan for renewing your metadata appropriately. We recommend expiry times of 1-3 years for root metadata. For targets metadata, recommended expiry times vary. If you are using offline updates, you may wish to opt for long expiry times, to ensure your offline updates stay valid for a long time after they’re issued. If all of your updates are OTA, you might choose a shorter period--say, 30 days. Metadata expiry times can be set in uptane-sign via the --expires or --expire-after command-line options. For more details about Uptane role expiry, you can consult the deployment best practices guidelines published by the Uptane project.

Prerequisites

• Account registered in the Torizon Cloud
• Practical experience with the Torizon Update Features
• The credentials.zip file downloaded from your Torizon Cloud account section
• The uptane-sign command line tool: download and extract the tarball from the GitHub page
• Java Runtime Environment 8 or later on the host machine to run uptane-sign tool

Types of Keys

Torizon Cloud aligns with the Uptane framework for software update security. Under Uptane, there are different keys used for different purposes.

For this article, you should know that there is a key used as the root of trust, and a different key used for signing software. The root of trust key is responsible for dictating what keys can be used for what purpose.

The software signing key - referred to in Uptane/TUF terminology as the targets key - is responsible for signing metadata about which software packages are valid for install.

Procedures

Rotate Keys Offline

To take these keys offline, you will use uptane-sign, a general-purpose command line tool for managing Uptane software repositories, metadata, and signing keys. It’s written in Scala, so you’ll need a Java runtime environment (8+) installed to use it. To get started, download the tarball from the link above and extract it. The uptane-sign executable is inside the /bin directory.

Rotating keys offline is a 6-step process:

1. Create a local Uptane metadata repository
2. Generate or import your new signing keys
3. Pull the metadata from your Torizon Cloud repository into your local repo
4. Perform the key rotation
5. Sign targets metadata with the new software signing key
6. Push signed targets metadata to Torizon Cloud

You will be able to take these steps one by one, with examples.

Create a Local Uptane Metadata Repository

The following command creates an empty repository, configured and ready to pull down the metadata from Torizon Cloud:

$ uptane-sign init --repo myimagerepo --credentials /path/to/credentials.zip

Note that you need to download your credentials.zip file from the Torizon Cloud. It contains OAuth client credentials that uptane-sign will use to authenticate its API calls.

Generate or Import the New Signing Keys

The following commands will generate new signing keys, give them names for convenience later on, and place them in your repository:

$ uptane-sign key generate --repo myimagerepo --name myroot --type ed25519
$ uptane-sign key generate --repo myimagerepo --name mytargets --type ed25519

If you have existing keys you want to use, you can also do that. We support RSA4096, RSA2048 (not recommended), and Ed25519 keys. You can also use a hardware module like a Yubikey for offline signing. If you do, you’ll have to perform a couple of extra steps; see uptane-sign --help for more information.

Pull the Metadata From the Torizon Cloud Repository Into the Local Repository

The following command downloads the metadata from Torizon Cloud into your local directory structure:

$ uptane-sign targets pull --repo myimagerepo

Perform the Key Rotation

To rotate the keys, you need to issue new root metadata. The detailed requirements for updating root metadata can be found in the Uptane standard, but fortunately, you don’t have to do it manually: uptane-sign provides a convenience function for rotating keys:

$ uptane-sign move-offline --repo myimagerepo --old-root-alias origroot --new-root myroot --new-targets mytargets

This command performs the following tasks:

1. Downloads the root and targets keys from the Torizon Cloud
2. Generates new metadata authorizing the new root and targets keys (myroot and mytargets from the previous step), and de-authorizing the old root and targets keys

Sign Targets Metadata With the New Software Signing Key

Now that your software signing key has been taken offline, your devices will no longer accept the metadata signed by the old key. You must sign your targets metadata with the offline key you generated:

$ uptane-sign targets sign --repo myimagerepo --key-name mytargets

Push Signed Targets Metadata to Torizon Cloud

You now have valid, signed metadata on your computer. The final step is to push it up to Torizon Cloud, so your devices will be able to use it:

$ uptane-sign targets push --repo myimagerepo

Recreating the Credentials.zip file

Once you’ve taken your keys offline, you will no longer be able to use the web UI to upload packages. Instead, you will use torizoncore-builder to sign and upload your Torizon images and docker-compose files. However, your old credentials.zip file will no longer work--it doesn't include your new key.

Therefore, you will need to re-pack your offline signing keys back into a credentials.zip (the format torizoncore-builder expects) using the export-credentials subcommand:

$ uptane-sign export-credentials --repo myimagerepo --key-name mytargets --output offline-credentials.zip

There’s a lot more that uptane-sign can do; uptane-sign --help is a useful guide.

Advanced Uptane Features

Torizon Cloud provides an Uptane-compliant repository for you to use. If you feel comfortable digging a bit deeper into how Uptane and repository signing works, you can take advantage of those features, even though Toradex doesn't directly provide tooling to help you do so.

Multiple Keys and Thresholds

In the examples and documentation above, you have used a single signing key for each role, to keep things easier. Uptane supports the use of multiple signing keys, along with key thresholds. So you can, for example, elect to create 5 different root keys, and require that at least 4 of them to perform any further root-of-trust operations. Using multiple keys with key thresholds is the configuration Uptane recommends for the safety-critical environment it was designed for--the automotive industry.

Note: if you choose to set up multi-sig verification for software signing keys, you will no longer be able to use torizoncore-builder to push your packages to the platform--you'll have to use Uptane tooling directly. See uptane-sign --help for more details.

Hardware Security Modules

So far, you've used keys generated and stored on disk. If you want to be extra sure about the safety of your private key material, you can use hardware security modules. The uptane-sign has sub-commands that generate the minified, canonicalized metadata that the signature needs to be generated over, for ease of use in scripting or CI environments. You can pipe this output into whatever signing tool you see fit.

Below, you can see an example with openssl as a stand-in for an external signing tool, and using it to sign targets metadata. The example here uses RSA keys with the SSAPSS padding, but the process for Ed25519 is similar.

1. Add the pubkey from your Hardware Security Module to the repo; you'll need to export it as a PEM

$ uptane-sign user-keys importpub --repo myimagerepo --key-name myHSMtargets --input /path/to/myHSMtargets.pem

2. Generate the signature: sign the minified, canonicalized metadata with openssl

$ export signature=$(uptane-sign targets get-unsigned --repo myimagerepo | openssl dgst -sha256 -sigopt rsa_padding_mode:pss -sigopt rsa_pss_saltlen:-1 -sign tmp/root_private.pem | base64 -w0)

3. Use the signature to sign the metadata in your repository

$ uptane-sign targets sign --repo myimagerepo --signatures myHSMtargets=${signature}