An 12812
An 12812
Contents
1 Preface 1 Preface.................................................. 1
This document provides the information necessary for the user to effectively 1.1 Intended audience
use Code-Signing Tool (CST) with a Hardware Security Module (HSM)
and scope...................... 1
1.2 References................... 1
backend. It is primarily intended for users who are familiar with CST tool to sign
codes for the NXP High Assurance Boot (HAB). 2 Overview................................................1
2.1 PKCS#11 enabled
The document is valid for CST versions starting from 3.3.1. HSM............................... 2
2.2 Client/Server based
1.1 Intended audience and scope HSM............................... 2
3 Hands-on............................................... 3
This guide is intended for software, hardware, and system engineers who are
planning to use CST to perform code signing for HAB using keys persisted in
3.1 Dependencies...............3
3.2 Getting sources............ 3
an HSM.
3.3 Compiling sources........ 3
3.4 Usage........................... 4
1.2 References 3.5 Debugging.................. 11
• Code-Signing Tool User’s Guide, Code Signing Tool package downloadable on http://www.nxp.com. Search for
CST_TOOL.
• Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series using HAB (document AN4581).
• i.MX Secure and Encrypted Boot using HABv4, available in doc/imx/habv4 of the U-Boot project, on the
imx_v2018.03_4.14.98_2.0.0_ga GA release branch.
• Open Secure Socket Layer (OpenSSL), 2020, http://www.openssl.org.
• PKCS#11 wrapper library, 2020. https://github.com/OpenSC/libp11.
• The p11-kit web pages, 2020. http://p11-glue.freedesktop.org/p11-kit.html.
• The PKCS #11 URI Scheme, 2020. https://tools.ietf.org/html/rfc7512.
2 Overview
Refering to Appendix B, Replacing the CST Backend Implementation of Code-Signing Tool User’s Guide, NXP has architected
the Code-Signing Tool in two parts a Front-End and a Back-End. The Front-End contains all the NXP proprietary operations,
while the Back-End containing all standard cryptographic operations. Users can write a replacement for the reference backend
to, for example, interface with an HSM or Smartcard.
The reference backend uses OpenSSL to perform HAB signature generation and encrypted data generation. OpenSSL in his
turn, exposes an Engine API, which makes it possible to plug in alternative implementations for some of the cryptographic
operations implemented by OpenSSL. We can take advantage of this to reuse the reference backend with an HSM, for example,
by offloading cryptographic operations involved during signature generation to HSM.
The engine should re-write an implementation of RSA private encrypt function, and how public certificates and private keys are
loaded from the HSM to the appropriate OpenSSL data structure: X509, RSA and EVP_PKEY. Optionally SHA digest functions
can be re-written also to be performed at the HSM level.
NXP Semiconductors
Overview
To link the CST Frontend to the Backend, a new adaptation layer has been developed to implement two APIs used by the
Frontend.
• gen_sig_data: The CST Front End uses this API to generate HAB signatures. In this function RSA and ECDSA signing
are offloaded to the OpenSSL PKCS#11 engine to be executed in the HSM, Smartcard etc.
• get_der_encoded_certificate_data: The CST frontend uses this API to read certificate in DER format. Given a
PKCS#11 URI, this function loads a certificate content to a X509 data structure.
Libp11 (openssl-pkcs11) is used as PKCS#11 engine for OpenSSL. Libp11 is also a PKCS#11 library which implements all
required functions to manage session and tokens, load public certificates, private keys, sign and hash. Slight modification has
been be done at the reference backend to initialize the engine, perform control command and configuration. Libp11 provides a
gateway between vendor’s PKCS#11 modules (PKCS#11 provider) and the OpenSSL engine API.
The PKCS#11 engine could access directly a PKCS#11 provider. An alternative could be using the p11-kit proxy module which
provides access to any configured PKCS #11 module in the system See http://p11-glue.freedesktop.org/p11-kit.html for more
information.
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 2 / 13
NXP Semiconductors
Hands-on
1. Locate keys/certificates on HSM by an identifier, name or label. This identifier will be kept across cryptographic
operation.
2. Load partial attributes of private key. In case of RSA should be able to get the value of the modulus and the exponent. It
is mandatory to populate RSA structure with those parameters for private keys. OpenSSL uses that for consistency
check between certificate and its corresponding private key. In case your HSM is not able to provide partial private keys
parameters, you should patch OpenSSL to ignore X509_check_private_key function.
3. Write an implementation for RSA init/finish methods and rsa_priv_encrypt method.
4. Optionally implement SHA diget methods if you want to perform digesting at HSM level. Methods are: digest_init,
digest_update, digest_finish, digest_copy, and digest_cleanup.
3 Hands-on
The following instructions will get you a copy of the engine backend implementation and pre-built frontend to build CST up and
running on your local machine for development and testing purposes.
The steps described in this section have been tested on an x86_64 machine running Ubuntu 16.04 and as root user.
3.1 Dependencies
The CST engine backend depends on:
OpenSSL library
$ gcc -v
The result is libbackend.a static library and cst binary present in the current working folder.
3. Install CST
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 3 / 13
NXP Semiconductors
Hands-on
$ make install
3.4 Usage
This section provides instructions and prerequisites to deploy Code-Signing Tool with SoftHSM2. SoftHSM2 will be used as an
HSM emulator.
NOTE
All actions are executed with root privileges on a Ubuntu 16.0.4 machine.
For SoftHSM we need to create the following folder, otherwise it fails initializing the token later.
$ mkdir -p /var/lib/softhsm/tokens/
SoftHSM2 uses file-based storage by default and this folder holds the tokens.
2. Install PKCS#11 utilities
To interact with HSM you can use OpenSC utilities.
The version used in this example is 0.4.7-3. If you are using an earlier version, it is highly recommended to upgrade.
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 4 / 13
NXP Semiconductors
Hands-on
In systems with p11-kit-proxy engine_pkcs11 has access to all the configured PKCS #11 modules and requires no further
configuration.
$ ls /usr/share/p11-kit/modules/
opensc-pkcs11.module p11-kit-trust.module softhsm2.module
Assume that there is no entry for you HSM, you can create a new one by defining the path to the HSM vendor’s PKCS#11
library and the priority.
The following is an entry for softhsm2. module in case it is not automatically created during installation.
# p11-kit list-modules
softhsm2: /usr/lib/softhsm/libsofthsm2.so
library-description: Implementation of PKCS11
library-manufacturer: SoftHSM
library-version: 2.2
token: CST-HSM-DEMO
manufacturer: SoftHSM project
model: SoftHSM v2
serial-number: 08e3dc40e2c3ac6a
hardware-version: 2.2
firmware-version: 2.2
--truncated
$ export PKCS11_MODULE=/usr/lib/x86_64-linux-gnu/p11-kit-proxy.so
export PKCS11_MODULE=/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 5 / 13
NXP Semiconductors
Hands-on
$ export SO_PIN=7635005489180126
$ export USR_PIN=12345678
3. Initialize a token:
The token label, CST-HSM-DEMO, will be used later with CST to locate certificates and keys needed to sign images.
4. To make sure that the pkcs11-tool interacts correctly with the HSM and the HSM is properly configured you can invoke
a simple command to display general information about the token
If you get an error invoking the command, usually in old OpenSSL versions, this is because libengine-pkcs11-openssl
writes its engine files to /usr/lib/ssl/engines rather than the location where current OpenSSL looks for engines.
Manually loading the PKCS#11 engine by defining the correct path to libraries should succeed.
To prevent loading the PKCS#11 engine manually each time we want to execute a command within the token, add the
following entries to /etc/ssl/openssl.cnf:
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 6 / 13
NXP Semiconductors
Hands-on
This line must be placed at the top, before any sections are defined:
openssl_conf = openssl_def
[openssl_def]
engines = engine_section
[engine_section]
pkcs11 = pkcs11_section
[pkcs11_section]
engine_id=pkcs11
dynamic_path = /usr/lib/engines/engine_pkcs11.so
MODULE_PATH = <PATH TO PKCS#11 MODULE>
init = 0
Set the MODULE_PATH parameter to the path of PKCS#11 library depending on your choice to use or not p11-kit.
System without p11-kit:
MODULE_PATH = /usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so
MODULE_PATH = /usr/lib/x86_64-linux-gnu/p11-kit-proxy.so
Try again:
3.4.2.1 HABv4
The PKI tree for this example is simple and it will be based on one SRK key. The SRK is chosen to be a CA key. The key length
is 2048 bits.
The first SRK as the root of trust. The CSF 1 and IMG 1 keys are used to sign the CSF data and the image respectively. For
more details, refer to CST documentation and Secure Boot Application Notes.
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 7 / 13
NXP Semiconductors
Hands-on
$ pushd ../../../crts/
$ touch index.txt
$ echo "unique_subject = no" > index.txt.attr
export CA_KEY="CA1_sha256_2048_ca"
openssl req -engine pkcs11 -new -batch -subj "/CN=${CA_KEY}/" -key "label_${CA_KEY}" -keyform
engine -out ${CA_KEY}.pem -text -x509 -days 3640 -config ../ca/openssl.cnf
Enter User PIN when prompts (if not specified in configuration file).
The flag, label_, identifies the key label you’re using. If you want to refer to a different token or key id, you can change
these.
5. Generate SRK key and certificate.
export SRK1_KEY="SRK1_sha256_2048_ca"
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 8 / 13
NXP Semiconductors
Hands-on
openssl req -engine pkcs11 -new -batch -subj "/CN=${SRK1_KEY}/" -keyform engine -key "label_$
{SRK1_KEY}" -out temp_srk_req.pem
Clean.
rm temp_srk_req.pem
export CSF1_KEY="CSF1_1_sha256_2048_usr"
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 9 / 13
NXP Semiconductors
Hands-on
Clean.
rm temp_csf_req.pem
export IMG1_KEY="IMG1_1_sha256_2048_usr"
Clean.
rm temp_img_req.pem
8. Verify that all cryptographic materials were written correctly to token by running.
List all objects.
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 10 / 13
NXP Semiconductors
Hands-on
[Header]
Version = 4.3
Hash Algorithm = sha256
Engine = CAAM
Engine Configuration = 0
Certificate Format = X509
Signature Format = CMS
[Install SRK]
File = "./SRK_1_table.bin"
Source index = 0
[Install CSFK]
File = "pkcs11:token=CST-HSM-DEMO;object=CSF1_1_sha256_2048_usr;type=cert;pin-value=12345678"
[Authenticate CSF]
[Unlock]
Engine = CAAM
Features = MID
[Unlock]
Engine = CAAM
Features = MFG
[Install Key]
Verification index = 0
Target index = 2
File = "pkcs11:token=CST-HSM-DEMO;object=IMG1_1_sha256_2048_usr;type=cert;pin-value=12345678"
[Authenticate Data]
Verification index = 2
Blocks = 0x7e0fc0 0x0 0x2bc00 "flash.bin"
3.4.5 Sign
Generate the CSF binary signature.
3.5 Debugging
To trace the PKCS#11 flow between CST and the HSM, pkcs11-spy tool could be used.
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 11 / 13
NXP Semiconductors
Hands-on
For security reason, you should only use the tool for debugging, and preferable only with test keys as the tool logs all calls including
PIN, signatures, etc.
Set the log output to a file:
export PKCS11SPY_OUTPUT=cst.log
Define the path to the real PKCS#11 library depending on if the system is with or without p11-kit.
Assume we are using SoftHSM2 on system without p11-kit.
export PKCS11SPY=/usr/lib/x86_64-linux-gnu/softhsm/libsofthsm2.so
MODULE_PATH=/usr/lib/x86_64-linux-gnu/pkcs11-spy.so
Invoke cst again. A cst.log file should be available with all the invoked calls with the associated arguments dump.
0: C_GetFunctionList
2020-04-23 15:38:25.647
Returned: 0 CKR_OK
1: C_Initialize
2020-04-23 15:38:25.647
[in] pInitArgs = (nil)
Returned: 0 CKR_OK
….
469: C_Sign
2020-04-23 15:38:25.701
[in] hSession = 0x11
…
Returned: 0 CKR_OK
Using Code-Signing Tool with Hardware Security Module, Rev. 0, June 2020
Application Note 12 / 13
How To Reach Us Information in this document is provided solely to enable system and software implementers to
use NXP products. There are no express or implied copyright licenses granted hereunder to
Home Page:
design or fabricate any integrated circuits based on the information in this document. NXP
nxp.com reserves the right to make changes without further notice to any products herein.
Web Support: NXP makes no warranty, representation, or guarantee regarding the suitability of its products for
nxp.com/support any particular purpose, nor does NXP assume any liability arising out of the application or use
of any product or circuit, and specifically disclaims any and all liability, including without limitation
consequential or incidental damages. “Typical” parameters that may be provided in NXP data
sheets and/or specifications can and do vary in different applications, and actual performance
may vary over time. All operating parameters, including “typicals,” must be validated for each
customer application by customer's technical experts. NXP does not convey any license under
its patent rights nor the rights of others. NXP sells products pursuant to standard terms and
conditions of sale, which can be found at the following address: nxp.com/
SalesTermsandConditions.
While NXP has implemented advanced security features, all products may be subject to
unidentified vulnerabilities. Customers are responsible for the design and operation of their
applications and products to reduce the effect of these vulnerabilities on customer’s applications
and products, and NXP accepts no liability for any vulnerability that is discovered. Customers
should implement appropriate design and operating safeguards to minimize the risks associated
with their applications and products.
NXP, the NXP logo, NXP SECURE CONNECTIONS FOR A SMARTER WORLD, COOLFLUX,
EMBRACE, GREENCHIP, HITAG, I2C BUS, ICODE, JCOP, LIFE VIBES, MIFARE, MIFARE
CLASSIC, MIFARE DESFire, MIFARE PLUS, MIFARE FLEX, MANTIS, MIFARE ULTRALIGHT,
MIFARE4MOBILE, MIGLO, NTAG, ROADLINK, SMARTLX, SMARTMX, STARPLUG, TOPFET,
TRENCHMOS, UCODE, Freescale, the Freescale logo, AltiVec, C‑5, CodeTEST, CodeWarrior,
ColdFire, ColdFire+, C‑Ware, the Energy Efficient Solutions logo, Kinetis, Layerscape, MagniV,
mobileGT, PEG, PowerQUICC, Processor Expert, QorIQ, QorIQ Qonverge, Ready Play,
SafeAssure, the SafeAssure logo, StarCore, Symphony, VortiQa, Vybrid, Airfast, BeeKit,
BeeStack, CoreNet, Flexis, MXC, Platform in a Package, QUICC Engine, SMARTMOS, Tower,
TurboLink, UMEMS, EdgeScale, EdgeLock, eIQ, and Immersive3D are trademarks of NXP B.V.
All other product or service names are the property of their respective owners. AMBA, Arm,
Arm7, Arm7TDMI, Arm9, Arm11, Artisan, big.LITTLE, Cordio, CoreLink, CoreSight, Cortex,
DesignStart, DynamIQ, Jazelle, Keil, Mali, Mbed, Mbed Enabled, NEON, POP, RealView,
SecurCore, Socrates, Thumb, TrustZone, ULINK, ULINK2, ULINK-ME, ULINK-PLUS, ULINKpro,
µVision, Versatile are trademarks or registered trademarks of Arm Limited (or its subsidiaries) in
the US and/or elsewhere. The related technology may be protected by any or all of patents,
copyrights, designs and trade secrets. All rights reserved. Oracle and Java are registered
trademarks of Oracle and/or its affiliates. The Power Architecture and Power.org word marks
and the Power and Power.org logos and related marks are trademarks and service marks
licensed by Power.org.
© NXP B.V. 2020. All rights reserved.
For more information, please visit: http://www.nxp.com
For sales office addresses, please send an email to: [email protected]