To sign an image, you must first generate several certificates (each with its own private key). This is a manual process and the PKI tree must be in place before you configure your Digi Embedded Yocto 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.

    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 firmware image itself.

    This certificate is also used to validate secure firmware update packages (.swu files).

Generate a Public Key Infrastructure (PKI) tree

  1. Download and extract the NXP Code Signing Tool (CST) from NXP servers and place it under your Digi Embedded Yocto installation directory (by default /usr/local/dey-3.2). Note that you will need to register with the NXP website.

  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 <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
    1234

    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 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 /usr/local/dey-3.2/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.

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

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

Add this line to your local.conf file to use the generated keys:

TRUSTFENCE_SIGN_KEYS_PATH = /path/to/keys