Manually create a Public Key Infrastructure tree (PKI tree)

Before building a signed U-Boot image, several certificates (each one with its own key) must be generated. This is a manual process and the PKI tree must be in place before you configure your Digi Embedded for Android project for secure boot.

Each certificate has a different purpose and name:

CA (Certification Authority): This certificate is used to sign the SRK keys and establish the author of the other keys. There is only one CA certificate per PKI tree. This certificate is never used on the target and has no requirements. An existing certificate can be used as CA during the generation of all these keys. The remainder of the keys and certificates are always generated and have special requirements, as they are directly used on the target.

SRK (Super Root Keys): This certificate is used to sign the CSF and IMG certificates. There are up to four SRK certificates per PKI tree (each one is used to sign one CSF and one IMG certificates). See Revoke a key for more information on having multiple SRK certificates.

CSF (Command Sequence File): This certificate is used to validate the CSF region
IMG: This certificate is used to validate the U-Boot image.

Generate a Public Key Infrastructure (PKI) tree

If you have not previously done so, download the NXP Code Signing Tool (CST) and include it in the Android sources directory. Note that you will need to register with the NXP website. You can find instructions in device/digi/common/trustfence/cst/README.txt.

Secure boot support
~~~~~~~~~~~~~~~~~~~
Digi Embedded for Android (DEA) uses NXP's Code signing Tool (CST) for the
High Assurance Boot library when generating secure firmware images. You must
download the CST tool and unpack it into this directory. Also, some patches
need to be applied before using it.
Basic instructions:
# cd dea-<version>/device/digi/common/trustfence/cst
# tar xf cst-2.3.2.tar.gz
# cd cst-2.3.2
# for i in ../patch/*.patch; do patch -p1 < $i; done

If you already have a certificate that you want to use as CA, skip this step. Otherwise, create a plain text file called serial inside the <CST_path>/keys folder. The content of this file must be a positive 32-bit number that uniquely identifies the certificate per certification authority.

<CST_path>/keys/serial

Also, create a plain text file called key_pass.txt inside the <CST_path>/keys folder. This file defines the password (at least four characters long) to be used to protect all the generated private keys. The content of this file is the password repeated twice:

<CST_path>/keys/key_pass.txt

my_pass_phrase
my_pass_phrase

The user is responsible for protecting the pass phrase for the private keys and the private keys themselves.

Loss of the pass phrase or the private keys will result in not being able to sign code with the affected keys.

In order to customize the certificate information (company name, country, email, etc.), edit the configuration files under the ca folder. Refer to the OpenSSL documentation for more information about those files.

Use the hab_pki_tree bash script to generate the PKI tree.

user:/dea-<version>/device/digi/common/trustfence/cst/cst-2.3.2/keys$ ./hab4_pki_tree.sh
(...)
Do you want to use an existing CA key (y/n)?: n
Do you want to use Elliptic Curve Cryptography (ECC) (y/n)?: n
Enter key length in bits for PKI tree: 2048
Enter PKI tree duration (years): 10
How many Super Root Keys should be generated? 4
Do you want the SRK certificates to have the CA flag set? (y/n)?:

You will be asked about the following parameters:

You can use an existing key as CA key by answering 'y' in the first question and then providing the path without extension of the certificate and the key for the certificate to be used as CA.

If asked about using ECC cryptography, answer 'n', as RSA is used for the signature.

The following key sizes are supported: 1024, 2048 and 4096.

The PKI duration is used to compute the expiration date for the certificates.

Note HAB4 does not take into account the expiration date. A signed U-Boot image will remain valid if its certificate has expired.

You must generate four keys (for key revocation purposes).

The last question regarding the “CA flag” in the SRK must be answered as 'y'.

The complete PKI tree is created.

Use the new generated keys to sign your artifacts. In to your localconfig.mk file located in your Android sources directory set the path to the generated keys:

TRUSTFENCE_SIGN_KEYS_PATH := "/path/to/generated/keys"

For more information about the PKI tree and the PKI tree generation process, see the documentation under the doc directory.

Note The CST folder to be used in Android should only contain one PKI tree and no other security-related files (keys, certificates, passwords, etc.) in any subfolder. Attempting to use a CST folder with several PKI trees or extra certificates or keys could fail.