4.13. OTP KEYWRITER

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.

Table 4.2 Customer keys programmed in 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

  1. Generate x509 certificate from customer HSM
  2. Include Encrypted TIFS Keywriter in PDK (move to tifs_bin/ti-fs-keywriter-j721e.bin)
  3. Build PDK Keywriter app
  4. 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.
../_images/key_writer_procedure.png

Fig. 4.8 X509 Certificate generation procedure.

  1. OEM generates a random 256-bit number to be used as an AES encryption key for protecting the OTP extension data.
  2. The AES-256 key from step 1 is used to encrypt all X509 extension fields, which require encryption protection.
  3. 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
  4. 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.
  5. This X509 config is sigend using SMPK (priv).
  6. (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, in keys/ folder
  • gen_keywr_cert.sh will also generate SHA-512 hash of SMPK, SMEK, BMPK, and BMEK and store them in verify_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