1. Article purpose[edit | edit source]
The main purpose of this article is to explain how to use the secrets stored in an external Hardware Security Module (HSM) to sign a software image such as TF-A BL2 or even a FIP. This allows the user to perform a Trusted boot by establishing a Chain of Trust (CoT).
2. OSTL implementation[edit | edit source]
In the OSTL ecosystem, the Signing tool is used to sign the platform Trusted Firmware-A BL2 software that is loaded by the ROM code. The Trusted Firmware-A FIP contains the firmware images loaded by the Trusted Firmware-A BL2 and their configuration files. The cert_create tool [1] handles the signature and the certificate chain generation for the binaries contained in the FIP. Both tools support the use of an external HSM.
3. Use case[edit | edit source]
This article is useful for people who want to sign firmware without having to manipulate a plain private key at some point. One may not want such secrets to be accessible at all. This can be done by interfacing an HSM where the secrets are securely stored with a signing tool.
4. Prerequisites[edit | edit source]
Following this article, it is mandatory that:
- The HSM you are using can be accessed using PKCS#11 APIs.
- You are running an OpenSSL version that supports engines. OpenSSL engines are deprecated [2] since OpenSSL version 3.0 but are still implemented. Therefore, most OpenSSL versions above 0.9.6 should fit to perform the operation.
- You have generated a key pair and stored the private key in the HSM.
 Information
|
| Some packages like OpenSSL are already included in the OSTL SDK. |
5. Perform a binary signature[edit | edit source]
First, check the openSSL version:
openssl version OpenSSL 3.2.2 4 Jun 2024 (Library: OpenSSL 3.2.2 4 Jun 2024)
Check that the PKCS#11 engine is correctly set:
openssl engine pkcs11 -t
(pkcs11) pkcs11 engine
[ available ]
Create a custom openSSL configuration file containing:
openssl_conf = openssl_conf
[openssl_conf]
engines = engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id = pkcs11
dynamic_path = <path_to_libpkcs11.so> #Usually /usr/lib/x86_64-linux-gnu/engines-xxx/libpkcs11.so
MODULE_PATH = <path_to_HSM_module_library>
and use it as openSSL configuration file:
export OPENSSL_CONF=<path_to_your_custom_config_file>
5.1. Perform a signature using only openSSL[edit | edit source]
Simply use the PKCS#11 URL of the private key that you want to use to perform the signature:
openssl dgst -engine pkcs11 -sign "<PKCS11_URL_OF_THE_PRIVATE_KEY>" -keyform engine -out test_signed.bin test.txt engine "pkcs11" set.
Note that this does not generate the certificates necessary to implement the CoT.
5.2. Perform Trusted Firmware-A FIP signature with PKCS#11[edit | edit source]
At this stage, the process is exactly the same as the one described in the TF-A BL2 Trusted Board Boot article. Simply specify the PKCS#11 URLs in the key arguments instead of the paths to *.pem files.
| Information
|
| The PKCS#11 URLs must be enclosed with the double quote (") character. For example: ROT_KEY="\"<PKCS11_URL_OF_THE_PRIVATE_KEY>\"" |
6. Example with a software HSM[edit | edit source]
6.1. Additional prerequisites[edit | edit source]
This section shows an example of software HSM. The SoftHSMv2 [3] is used, which is a software implementation of a generic cryptographic device with a PKCS#11 interface. To set up the environment:
- Make sure the following packages are installed:
- pkcs11-tools provided in the opensc package
- p11tool provided in the gnutls-bin package
- libengine-pkcs11-openssl
- Install SoftHSMV2.
6.2. Setup[edit | edit source]
The fields enclosed <this_way> are supposed to be replaced by your absolute paths.
- First, create a working directory to store the configuration files and tokens:
cd $HOME mkdir -p softhsm/tokens cd softhsm
- Copy the SoftHSMv2 default configuration file:
cp /etc/softhsm2.conf .
- Customize the token directory path in this configuration file:
Insert "directories.tokendir = <path_to>/softhsm/tokens" in softhsm2.conf
- Export the SOFTHSM2_CONF environment variable:
export SOFTHSM2_CONF=<path_to>/softhsm/softhsm2.conf
- Display the slots:
softhsm2-util --show-slots
Available slots:
Slot 0
Slot info:
Description: SoftHSM slot ID 0x0
Manufacturer ID: SoftHSM project
Hardware version: 2.6
Firmware version: 2.6
Token present: yes
Token info:
Manufacturer ID: SoftHSM project
Model: SoftHSM v2
Hardware version: 2.6
Firmware version: 2.6
Serial number:
Initialized: no
User PIN init.: no
Label:
- Initialize the token with a given label. SO PIN is the administrator PIN, User PIN is used to access the slot:
softhsm2-util --init-token --slot 0 --label "TFASignFIP" === SO PIN (4-255 characters) === Please enter SO PIN: **** #0000 Please reenter SO PIN: **** === User PIN (4-255 characters) === Please enter user PIN: **** #1234 Please reenter user PIN: **** The token has been initialized and is reassigned to slot 1861710895
- Check the module:
pkcs11-tool --show-info --module /usr/local/lib/softhsm/libsofthsm2.so Cryptoki version 2.40 Manufacturer SoftHSM Library Implementation of PKCS11 (ver 2.6) Using slot 0 with a present token (0x6ef7742f) #1861710895
| Information
|
| To ease manipulations, you can create an alias to pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so |
alias p11-softhsm="pkcs11-tool --module /usr/local/lib/softhsm/libsofthsm2.so"
- List all the available slots:
p11-softhsm --list-slots Available slots: Slot 0 (0x6ef7742f): SoftHSM slot ID 0x6ef7742f token label : TFASignFIP token manufacturer : SoftHSM project token model : SoftHSM v2 token flags : login required, rng, token initialized, PIN initialized, other flags=0x20 hardware version : 2.6 firmware version : 2.6 serial num : 1eb49a0ceef7742f pin min/max : 4/255 Slot 1 (0x1): SoftHSM slot ID 0x1 token state: uninitialized
- Generate a keypair using pkcs11-tools:
p11-softhsm --login --login-type user --keypairgen --id 0 --key-type EC:secp256r1 --slot 1861710895 Logging in to "TFASignFIP". Please enter User PIN: #Enter User PIN Key pair generated: Private Key Object; EC label: ID: 00 Usage: decrypt, sign, unwrap, derive Access: sensitive, always sensitive, never extractable, local Public Key Object; EC EC_POINT 256 bits EC_POINT: 044104510cedc7dabaa4b3a7f9953069065d3f9b3978d772e3c04069c34f4198a5bda64e16ec685c9dadbe91c5f35a76362d8c955a4167e78e3f1365e98ab05f7884a4 EC_PARAMS: 06082a8648ce3d030107 label: ID: 00 Usage: encrypt, verify, wrap, derive Access: local
- List and get the private key URL with p11tool:
p11tool --provider=/usr/local/lib/softhsm/libsofthsm2.so --login --set-pin=1234 --list-all Object 0: URL: pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=1eb49a0ceef7742f;token=TFASignFIP;id=%00;type=private #This is the URI Type: Private key (EC/ECDSA-SECP256R1) Label: Flags: CKA_WRAP/UNWRAP; CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE; ID: 00 Object 1: URL: pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=1eb49a0ceef7742f;token=TFASignFIP;id=%00;type=public Type: Public key (EC/ECDSA-SECP256R1) Label: Flags: CKA_WRAP/UNWRAP; ID: 00
- Create a custom openSSL configuration file (for example openssl-pkcs11.conf) with the content described here, and add:
MODULE_PATH = /usr/local/lib/softhsm/libsofthsm2.so
- Export the OPENSSL_CONF environment variable:
export OPENSSL_CONF=<path_to>/softhsm/openssl-pkcs11.conf
- Sign a binary using the PKCS11 URL:
openssl dgst -engine pkcs11 -sign "pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=1eb49a0ceef7742f;token=TFASignFIP;id=%00;object=tfasign;type=private" -keyform engine -out test_signed.bin test.txt engine "pkcs11" set.
| Information
|
| At this stage, and similarly to the procedure above, the PKCS11 URLs can be used to generate the CoT certificates |
7. Troubleshooting[edit | edit source]
- If you cannot enumerate slots as shown below, it means that the openSSL configuration file is incorrect or that the OPENSSL_CONF variable has not been defined. In this case, please check it.
openssl dgst -engine pkcs11 -sign "pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=1eb49a0ceef7742f;token=TFASignFIP;id=%00;object=tfasign;type=private" -keyform engine -out signature.bin test.txt engine "pkcs11" set. Failed to enumerate slots Failed to enumerate slots PKCS11_get_private_key returned NULL cannot load key file from engine 140310533596480:error:80067065:pkcs11 engine:ctx_load_privkey:object not found:eng_back.c:858: 140310533596480:error:26096080:engine routines:ENGINE_load_private_key:failed loading private key:../crypto/engine/eng_pkey.c:77: unable to load key file
- If you cannot find the key, it is likely that your SOFTHSM2_CONF variable has not been set or that you configuration file is not correct.
openssl dgst -engine pkcs11 -sign "pkcs11:model=SoftHSM%20v2;manufacturer=SoftHSM%20project;serial=1eb49a0ceef7742f;token=TFASignFIP;id=%00;object=tfasign;type=private" -keyform engine -out signature.bin test.txt engine "pkcs11" set. Specified object not found Specified object not found PKCS11_get_private_key returned NULL cannot load key file from engine 140107714262336:error:80067065:pkcs11 engine:ctx_load_privkey:object not found:eng_back.c:858: 140107714262336:error:26096080:engine routines:ENGINE_load_private_key:failed loading private key:../crypto/engine/eng_pkey.c:77: unable to load key file Segmentation fault
8. References[edit | edit source]