To sign a bootloader image, you must first generate several certificates (each with its own private key).

The trustfence-tools-ccimx8xsbcpro-trusty.zip build artifact includes a signing script (trustfence-sign-uboot.sh) that generates the required keys and certificates if they are not found. But it is possible to manually generate the PKI tree before you sign your images.

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 bootloader sign key for more information on having multiple SRK certificates.

  • CSF (Command Sequence File): This certificate is used to validate the CSF region.

    The CSF region is a binary blob that contains technical information about the signature (key size, algorithm used, etc.) that is appended to the binary file during signing.

  • IMG: This certificate is used to validate the bootloader image itself.

Generate a Public Key Infrastructure (PKI) tree

  1. Install Code Signing Tool (CST).

    Digi Embedded for Android uses NXP’s Code Signing Tool (CST) for the High Assurance Boot library when generating secure firmware images.

    1. Download CST 3.3.1 from https://www.nxp.com/webapp/Download?colCode=IMX_CST_TOOL_NEW&location=null.

    2. Decompress the package, for example to your home directory, /home/<user>:

      $ tar zxvf cst-3.3.1.tgz -C ~

    3. Add the directory linux64/bin to your path:

      $ export PATH=~/cst-3.3.1/linux64/bin:$PATH

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

    ~/cst-3.3.1/keys/serial
    1234

    Also, create a plain text file called key_pass.txt inside the the keys directory of the CST folder, ~/cst-3.3.1/keys. 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-3.3.1/keys/key_pass.txt
    my_pass_phrase
my_pass_phrase
    The user is responsible for protecting the pass phrase for the private keys as well as 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.

    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.

  3. Use the hab4_pki_tree bash script to generate the PKI tree. You will be asked about the following parameters:

    $ cd ~/cst-3.3.1/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: 4096
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 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.

    HAB 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.

    At this point, the script creates the complete PKI tree.

  4. To use the generated keys, set your CONFIG_SIGN_KEYS_PATH to use the generated keys. Then continue with the steps at Sign bootloader images.

    The CST folder to be used in Digi Embedded for 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.

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