4.13. OTP KEYWRITER¶
Table of Contents
4.13.1. Introduction¶
Note
This document is applicable to High Secure (HS) device variants.
OTP (One Time Programmable) Keywriter is the software tool, used to provision customer keys into the device eFuses for enforcing secure boot and establishing root of trust. Secure boot requires an image to be encrypted and signed using customer keys, which will be verified by the SoC using active MEK (for decryption) and MPK Hash (to verify the signature). In case the customer’s MPK and MEK are compromised, there is a second set of MPK and MEK that can be used, after a keyrevision update.
In order to burn the 2 sets (active and backup) of customer key information into the SoC, OTP Keywriter requires a x509 format certificate, signed using customer key(s) (Programming of backup key set is optional).
Note
This action is irreversible, so there is no going back once the keys are burned into SoC eFuses.
Acronym | Name | Notes |
---|---|---|
SMPKH | Secondary Manufacturer Public Key Hash | SMPK is 4096-bit customer RSA signing key |
SMEK | Secondary Manufacturer Encryption Key | 256-bit Customer encryption key for encrypted boot |
BMPKH | Backup Manufacturer Public Key Hash | BMPK is 4096-bit customer RSA signing key |
BMEK | Backup Manufacturer Encryption Key | 256-bit Customer encryption key for encrypted boot |
Limitations
Current version of OTP Keywriter only supports 4096 bit RSA format for SMPK and BMPK. Support for ECDSA and different key lengths will be available in subsequent versions.
4.13.2. Components¶
OTP Keywriter contents include:
PDK keywriter app source code
This is the public keywriter application. It boots directly on the primary boot core of the device (generically, not necessarily R5) without any other bootloader. It is responsible for sending the OTP configuration to the secure keywriter to blow the keys into the device eFuses.
- x509 certificate configuration template, and generation script as a part of source code
Note
This is a reference script. It can either be used as-is with the customer’s keys or integrated within the customer’s HSM environment.
Encrypted TIFS keywriter binary
This is the secure OTP keywriter firmware, and runs on the secure subsystem of the device (not necessarily M3, or even DMSC). It is responsible for verifying the OTP configuration from x509 certificate and blowing the data into the device efuses.
Note
This binary is different from the standard TIFS binary used in production.
TI FEK (public) key - TI Field Encryption Key
This will be required by certificate generation script, to ensure confidentiality of the customer’s key material. TI FEK Public key will be used to encrypt content (refer Fig. 4.8), and TI FEK private key (not shared, but accessible by encrypted TIFS keywriter binary) will be used to decrypt it (inside DMSC).
4.13.3. Directory Structure¶
keywriter/
├── init.asm
├── linker.lds
├── main.c
├── main.h
├── scripts
│ ├── gen_keywr_cert.sh /* x509 certificate generation script */
│ └── templates
│ ├── config_bmpk_template.txt
│ └── config_template.txt
└─── tifs_bin
└── ti-fs-keywriter-$(SOC).bin /* Encrypted TIFS-Keywriter binary, This is where
the binary will be copied into after secure download */
4.13.4. Build Procedure¶
- Generate x509 certificate from customer HSM
- Include Encrypted TIFS Keywriter in PDK (move to
tifs_bin/ti-fs-keywriter-j721e.bin
) - Build PDK Keywriter app
- Run on SoC, using a boot mode of choice
4.13.4.1. Generating x509 certificate from customer HSM¶
The Customer keys are supposed to be private, and not to be distributed out in open. For the scope of this document, Customer HSM would mean The secure server/ system where the customer intends to generate the x509 certificate. Once the certificate is generated, since the customer key information is encrypted, it is safe to share the certificate in open without revealing the actual keys.
Note
OpenSSL (1.1.1 11 Sep 2018) is required for building the OTP Keywriter. Check if OpenSSL is installed by typing “openssl version” at the comamnd prompt. If OpenSSL is not installed, download and install OpenSSL for your OS.
- For Windows : The easiest way is to download and install Strawberry Perl The Strawberry Perl installer automatically installs and sets up OpenSSL. Alternately, users can also use any of these Third Party OpenSSL Distributions for Windows. Refer individual links for instructions on how to setup OpensSSL using a particular distribution.
- For Linux : Execute the command
sudo apt-get install openssl
at the linux command prompt.
- OEM generates a random 256-bit number to be used as an AES encryption key for protecting the OTP extension data.
- The AES-256 key from step 1 is used to encrypt all X509 extension fields, which require encryption protection.
- Following X509 extensions are created, using TI FEK (public):
- Encrypting the AES-256 key with TI FEK
- Signing the AES-256 key with the SMPK, and encrypting that with the TI FEK
- (optionally, refer step 6) signing the AES-256 key with the BMPK, and encrypting that with the TI FEK
- All of the extensions from steps 1-3 are combined into a X.509 configuration which is used to generate and sign a certificate with the SMPK.
- This X509 config is sigend using SMPK (priv).
- (Optional) If the OEM chooses to write BMPK/BMEK fields, X509 config from step 5 needs to be signed using BMPK (priv).
The scripts folder has the necessary tools for generating x509 certificate for eFuse programming. It can be copied to a secure server (customer HSM) where the customer keys are stored, and used to generate the x509 certificate.
Run the gen_keywr_cert.sh
shell script, to create the certificate.
Modify the path arguments to specific keys as necessary. Use -h
option for help.
./gen_keywr_cert.sh -h
Tip
./gen_keywr_cert.sh -g
will generate dummy keys for testing, inkeys/
foldergen_keywr_cert.sh
will also generate SHA-512 hash of SMPK, SMEK, BMPK, and BMEK and store them inverify_hash.csv
. M3 logs will also print out SHA-512 hash of the keys.verify_hash.csv
can be used for quick comparision with M3 logs
Final certificate will be available in x509cert/final_certificate.bin
in
customer HSM, which needs to be exported to PDK Keywriter app directory
x509cert/final_certificate.bin
.
4.13.4.2. Building PDK Keywriter app¶
Keywriter app can be built, with following commands. In all below commands “make” can be replaced with “gmake” for Windows machine build. For more details about building the PDK, refer here
cd <pdk-install-path>/packages/ti/build/
make keywriter_img -j4
Final keywriter_img_<SoC>_release.tiimage
is available at
<pdk-install-path>/packages/ti/boot/sbl/example/k3MulticoreApp/binary
Note
The OTP Keywriter certificate from x509cert/final_certificate.bin
is appended to the pdk binary
<pdk-install-path>/packages/ti/boot/sbl/example/k3MulticoreApp/binary/keywriter_img_j721e_release.bin
and signed. So that the source code wouldn’t be compiled each time there is a change
in the OTP Keywriter certificate.
Note
Any changes in boardconfig would require the sciclient_boardcfg
and
sciclient_direct
modules to be built before keywriter_img
4.13.4.3. Running on SoC, using a boot mode of choice¶
The final keywriter_img_j721e_release.tiimage
is a bootable keywriter applcation
image containing the encrypted OTP keywrtiter binary, and OTP configuration data structure.
The PDK Keywriter app will load OTP Keywriter binary, and do an API call to eFuse programming API.
The response from TIFS API, gives information about success/failure in customer key programming in SoC eFuses.
This is logged on R5 UART Port, for confirmation to the user.
4.13.5. OTP Keywriter API¶
TISCI_MSG_KEY_WRITER is the message id to be used with Sciclient service to program customer key information into efuses.
4.13.5.1. TISCI Keywriter Message¶
TISCI Message ID | Message Name |
---|---|
0x9031U | TISCI_MSG_KEY_WRITER |
4.13.5.2. TISCI_MSG_KEY_WRITER¶
Message to program customer keys to SoC eFuse array
struct tisci_otp_process_key_cfg_req
Request to program efuses
Parameter | Type | Description |
---|---|---|
hdr | struct tisci_header | standard TISCI header |
image_addr_lo | uint32_t | Lower 32 bit address (in LE format) of the certificate |
image_addr_hi | uint32_t | Higher 32 bit address (in LE format) of the certificate |
key_prog_mask[2] | uint32_t | Reserved for future use |
struct tisci_otp_process_key_cfg_resp
Response from Keywriter API
Parameter | Type | Description |
---|---|---|
hdr | struct tisci_header | standard TISCI header |
debug_response | uint32_t | debug code for success/failure |
4.13.6. Debugging¶
The debug_response
from KEYWRITER API has detailed information about
success / failure in blowing eFuses on the SoC.
Following enum has the bit positions, which are set in debug_response
according
to specific issue while programming customer keys
Note
For example a debug_response
0x00000004 would mean that
(KEYWR_ERR_DECRYPT_BMPKH) there was an error in decrypting BMPKH extension field
/* Bit positions for debug status */
enum keywriter_error_codes {
/* Decryption Issues */
KEYWR_ERR_DECRYPT_AES256_KEY = 0,
KEYWR_ERR_DECRYPT_BMEK,
KEYWR_ERR_DECRYPT_BMPKH,
KEYWR_ERR_DECRYPT_SMEK,
KEYWR_ERR_DECRYPT_SMPKH,
/* Internal Operation issue */
KEYWR_ERR_INTERAL_OP,
/* Certificate creation issues */
KEYWR_ERR_INVALID_EXT_COUNT,
KEYWR_ERR_PARSE_CERT,
KEYWR_ERR_PARSE_FEK,
KEYWR_ERR_PARSE_SMPK_CERT,
/* eFuse programming issues*/
KEYWR_ERR_PROGR_BMEK,
KEYWR_ERR_PROGR_BMPKH_PART_1,
KEYWR_ERR_PROGR_BMPKH_PART_2,
KEYWR_ERR_PROGR_KEYCOUNT,
KEYWR_ERR_PROGR_KEYREV,
KEYWR_ERR_PROGR_SMEK,
KEYWR_ERR_PROGR_SMPKH_PART_1,
KEYWR_ERR_PROGR_SMPKH_PART_2,
/* Certificate validation issues */
KEYWR_ERR_VALIDATION_CERT,
KEYWR_ERR_VALIDATION_SMPK_CERT,
KEYWR_ERR_VALIDATION_BMPK_KEY,
KEYWR_ERR_VALIDATION_SMPK_KEY,
/* Write protect programming issues */
KEYWR_ERR_WRITE_PROT_KEYCOUNT,
KEYWR_ERR_WRITE_PROT_KEYREV,
};
INDEX | Description |
---|---|
KEYWR_ERR_DECRYPT_AES256_KEY | Error in Decrypting AES256 key randomly generated by customer |
KEYWR_ERR_DECRYPT_BMEK | Error in Decrypting BMEK extension field |
KEYWR_ERR_DECRYPT_BMPKH | Error in Decrypting BMPKH extension field |
KEYWR_ERR_DECRYPT_SMEK | Error in Decrypting SMEK extension field |
KEYWR_ERR_DECRYPT_SMPKH | Error in Decrypting SMPKH extension field |
KEYWR_ERR_INTERAL_OP | Internal Operation Error |
KEYWR_ERR_INVALID_EXT_COUNT | Invalid extension count in x509 certificate. Either SMPKH, SMEK pair or BMPKH, BMEK, SMPKH, SMEK should be used. Any other combination will trigger error |
KEYWR_ERR_PARSE_CERT | Error in parsing certificate |
KEYWR_ERR_PARSE_FEK | Error in parsing TI FEK (appended to TIFS binary, before encryption) |
KEYWR_ERR_PARSE_SMPK_CERT | Error in parsing SMPK signed certificate (certificate that contains customer key data) |
KEYWR_ERR_PROGR_BMEK | Error in programming BMEK into SoC eFuses |
KEYWR_ERR_PROGR_BMPKH_PART_1 | Error in programming BMPKH part 1 into SoC eFuses |
KEYWR_ERR_PROGR_BMPKH_PART_2 | Error in programming BMPKH part 2 into SoC eFuses |
KEYWR_ERR_PROGR_KEYCOUNT | Error in programming KEY COUNT into SoC eFuses |
KEYWR_ERR_PROGR_KEYREV | Error in programming KEY REV into SoC eFuses |
KEYWR_ERR_PROGR_SMEK | Error in programming SMEK into SoC eFuses |
KEYWR_ERR_PROGR_SMPKH_PART_1 | Error in programming SMPKH part 1 into SoC eFuses |
KEYWR_ERR_PROGR_SMPKH_PART_2 | Error in programming SMPKH part 2 into SoC eFuses |
KEYWR_ERR_VALIDATION_CERT | Error validating certificate |
KEYWR_ERR_VALIDATION_SMPK_CERT | Error validating SMPK signed certificate |
KEYWR_ERR_VALIDATION_BMPK_KEY | Error validating BMPK key |
KEYWR_ERR_VALIDATION_SMPK_KEY | Error validating SMPK key |
KEYWR_ERR_WRITE_PROT_KEYCOUNT | Error write protecting key count row |
KEYWR_ERR_WRITE_PROT_KEYREV | Error write protecting key revision row |
A debug_response
of 0x00 means the OTP Keywriter programming is a success.
Apart from debug_response, there are MCU R5 and M3 logs which help in debugging.
Note
To view OTP Keywriter M3 logs, system firmware logs have to be enabled. Procedure to do so can be found here.
Example logs, after a successful OTP Keywriter operation can be found here
4.13.7. Appendix¶
4.13.7.1. X509 Configuration Template¶
The following x509 configuration template is used, by gen_keywr_cert.sh
file,
to create the x509 certificate. Each key has an extension field
(OID 1.3.6.1.4.1.294.1.64 - 1.3.6.1.4.1.294.1.71), mentioning information such as SHA-512
value, size, IV, RS used in AES encryption.
[ req ]
distinguished_name = req_distinguished_name
x509_extensions = v3_ca
prompt = no
dirstring_type = nobmp
# This information will be filled by the end user.
# The current data is only a place holder.
# System firmware does not make decisions based
# on the contents of this distinguished name block.
[ req_distinguished_name ]
C = oR
ST = rx
L = gQE843yQV0sag
O = dqhGYAQ2Y4gFfCq0t1yABCYxex9eAxt71f
OU = a87RB35W
CN = x0FSqGTPWbGpuiV
emailAddress = kFp5uGcgWXxcfxi@vsHs9C9qQWGrBs.com
[ v3_ca ]
basicConstraints = CA:true
1.3.6.1.4.1.294.1.64 = ASN1:SEQUENCE:enc_aes_key
1.3.6.1.4.1.294.1.65 = ASN1:SEQUENCE:enc_smpk_signed_aes_key
1.3.6.1.4.1.294.1.66 = ASN1:SEQUENCE:enc_bmpk_signed_aes_key
1.3.6.1.4.1.294.1.67 = ASN1:SEQUENCE:aesenc_smpkh
1.3.6.1.4.1.294.1.68 = ASN1:SEQUENCE:aesenc_smek
1.3.6.1.4.1.294.1.70 = ASN1:SEQUENCE:aesenc_bmpkh
1.3.6.1.4.1.294.1.71 = ASN1:SEQUENCE:aesenc_bmek
[ enc_aes_key ]
# Replace PUT-ENC-AES-KEY with acutal Encrypted AES Key
val = FORMAT:HEX,OCT:PUT_ENC_AES_KEY
size = INTEGER:PUT_SIZE_ENC_AES
[ enc_bmpk_signed_aes_key ]
# Replace PUT-ENC-BMPK-SIGNED-AES-KEY with acutal Encrypted BMPK signed AES Key
val = FORMAT:HEX,OCT:PUT_ENC_BMPK_SIGNED_AES_KEY
size = INTEGER:PUT_SIZE_ENC_BMPK_SIGNED_AES
[ enc_smpk_signed_aes_key ]
# Replace PUT-ENC-SMPK-SIGNED-AES-KEY with acutal Encrypted SMPK signed AES Key
val = FORMAT:HEX,OCT:PUT_ENC_SMPK_SIGNED_AES_KEY
size = INTEGER:PUT_SIZE_ENC_SMPK_SIGNED_AES
[ aesenc_smpkh ]
# Replace PUT-AESENC-SPMKH with acutal Encrypted AES Key
val = FORMAT:HEX,OCT:PUT_AESENC_SMPKH
iv = FORMAT:HEX,OCT:PUT_IV_AESENC_SMPKH
rs = FORMAT:HEX,OCT:PUT_RS_AESENC_SMPKH
size = INTEGER:PUT_SIZE_AESENC_SMPKH
[ aesenc_smek ]
# Replace PUT-AESENC-SMEK with acutal Encrypted AES Key
val = FORMAT:HEX,OCT:PUT_AESENC_SMEK
iv = FORMAT:HEX,OCT:PUT_IV_AESENC_SMEK
rs = FORMAT:HEX,OCT:PUT_RS_AESENC_SMEK
size = INTEGER:PUT_SIZE_AESENC_SMEK
[ aesenc_bmpkh ]
# Replace PUT-AESENC-BMPKH with acutal Encrypted BMPKH
val = FORMAT:HEX,OCT:PUT_AESENC_BMPKH
iv = FORMAT:HEX,OCT:PUT_IV_AESENC_BMPKH
rs = FORMAT:HEX,OCT:PUT_RS_AESENC_BMPKH
size = INTEGER:PUT_SIZE_AESENC_BMPKH
[ aesenc_bmek ]
# Replace PUT-AESENC-BMEK with acutal Encrypted BMEK
val = FORMAT:HEX,OCT:PUT_AESENC_BMEK
iv = FORMAT:HEX,OCT:PUT_IV_AESENC_BMEK
rs = FORMAT:HEX,OCT:PUT_RS_AESENC_BMEK
size = INTEGER:PUT_SIZE_AESENC_BMEK
4.13.7.2. OTP KEYWRITER LOGS¶
R5 Log
OTP Keywriter ver: 20.8.5-w2020.17-am64x-10-g61bee
KEYWRITER APP
Beginning key programming sequence
Taking OTP configuration from 0x41c7e000
Debug response: 0x0
Key programming is complete
M3 Log
SMPKH Part 2 BCH code (u32) 0x36DD99C0
SMPKH Part 1 BCH code (u32) 0xDBCA50E0
SMPK Hash: 1f6002b07cd9b0b7c47d9ca8d1aae57b8e8784a12f636b2b760d7d98a18f189760dfd0f23e2b0cb10ec7edc7c6edac3d9bdfefe0eddc3fff7fe9ad875195527d
SMEK BCH code (u32) 0x4EDEC6A0
SMEK Hash: 92785809a3dfefea57f6bbed642d730ba5d05e601222a72e815bf01ceb3a50f96ab85d282425f684436fabd4c7da624b791da411615035314103cc64e611f532
BMPKH Part 2 BCH code (u32) 0x67AE6300
BMPKH Part 1 BCH code (u32) 0xE44C6400
BMPK Hash: 384be278a7a50eb25afdffac2e8bd306f82a3b51a770f8056c9ddeb9f31b0d3d3ea0063e6de3127a47c8a1443fc7e10dadffb51601aeaeb499d607e02874cd80
BMEK BCH code (u32) 0x3C735F40
BMEK Hash: 9352f2c8069698ad4a1e6dfb381723ba4a15948a5e00c5ac004f574f194efe66bc701d378b01ec0bf1a36bef6e7a931d466dbdb38bd2be0aad8afc756aa5ea7a
Success programming BMPKH part 1
Success programming BMPKH part 2
Success programming BMEK
Success programming SMPKH part 1
Success programming SMPKH part 2
Success programming SMEK
debug_response: 0x0