This section contains a summary of all the keys used in TrustFence, what they are used for, and how they should be backed up.

You are responsible for storing and protecting the private keys. Loss of the private keys will result in not being able to sign artifacts with the affected keys.

To maintain a high level of security, strictly limit the number of people who have access to your private keys.

Bootloader signature keys

The PKI tree is used for signing all the bootloader artifacts. It is automatically generated by TrustFence tools during the signing process if one does not already exist (see 5. Sign the bootloader images).

The PKI tree is composed of two subfolders:

  • crts: This folder contains only public information that does not need to be secured (public keys).

  • keys: This folder contains private information that should be securely stored (private keys and the password protecting them). The private key names adhere to the following pattern:

    • CA1_sha256_<key_size>_65537_v3_ca_key.<ext>

    • CSFn_1_sha256_<key_size>_65537_v3_usr_key.<ext>

    • IMGn_1_sha256_<key_size>_65537_v3_usr_key.<ext>

    • SRKn_sha256_<key_size>_65537_v3_ca_key.<ext>

Where <key_size> matches the public key size (1024, 2048, and 4096), <ext> matches the certificate or private key extension (.der or .pem) and n is the key index (1, 2, 3, or 4).

For security reasons, the secured machine signing the images should only have access to the set of keys for the index you have selected. If the key is compromised, it can be revoked and replaced by another one. See Revoke a bootloader sign key.

You must securely back up the entire PKI tree. Digi might require this PKI tree in order to accept RMAs of secured devices. Alternatively, you will be required to perform the signing of custom images and provide them to Digi.

RPMB authentication key

To enable access to RPMB, you must program an authentication key.

  • It is a 256-bit secure key to program in the OTP (One-Time Programmable) area of the eMMC.

  • This key is used to sign and verify data transferred between RPMB and Trusty.

  • The key can only be programmed once in device life time.

The saved copy of RPMB key is encapsulated with CAAM, and CAAM uses the value in eFuse hardware. The RPMB key blob encapsulated with CAAM is saved in the last block of BOOT1 partition. To prevent the key blob from been tampered with when the system is running, the BOOT1 partition is set with power-on write protection when the board boots up.

For more information on how to program RPMB authentication key, see 8. Initialialize the secure storage for Trusty OS.

AVB keys

The AVB key consists of a public key and a private key:

  • The private key is used by the host to sign the VBMeta struct in VBMeta image during the build process.

  • The public key is used to authenticate the VBMeta image in the device at runtime. This public key is read by Trusty and must be previously stored in RPMB secure storage.

Relationship between AVB key and vbmeta

For more information, see:

OTA and APK keys

By default, the Digi Embedded for Android build system uses five keys under device/digi/common/security:

  • testkey: Generic default key for packages that do not otherwise specify a key.

  • platform: Test key for packages that are part of the core platform.

  • shared: Test key for things that are shared in the home/contacts process.

  • media: Test key for packages that are part of the media/download system.

  • networkstack: Test key for packages that are part of the networking system.

See Certificates and private keys for more information.

These keys are used to sign applications (APKs) in the firmware and OTA packages:

  • All Android applications must be signed by a developer key or by the platform signing key to be granted signature permissions for those components. When an application is installed, the Package Manager verifies that the APK is properly signed with the certificate included in that APK.

  • OTA update packages must be signed with a key expected by the system.

Default keys are publicly known, so anybody can sign their own APKs with the same keys. This may allow third-party applications to access functionality reserved for system applications.

It is critical to sign your final artifacts with private release-keys that only you have access to. To do show see 4. Generate release images.

To sign applications not included in the build firmware but that will be installed at runtime, see Sign your application.