packages/ti/drv/sciclient/soc/sysfw/binaries/system-firmware-public-documentation/_sources/6_topic_user_guides/key_writer.rst.txt

   1 =========================
   2 Key  Writer
   3 =========================
   4
   5 This guide describes the procedure and :ref:`format <sysfw_pub_keywr_cert_format>` to
   6 be followed, to populate customer keys in eFuses of the SoC.
   7
   8 .. Note::
   9
  10     This document must be read along side :doc:`../2_tisci_msgs/security/keywriter`
  11
  12 High Security (HS) Device Sub-types
  13 ===================================
  14 #. **HS-FS (High Security - Field Securable)**:
  15    Device type before customer keys are programmed (the state at which the device
  16    leaves TI factory). In this state, device protects the ROM code, TI keys and certain
  17    security peripherals. HS-FS devices do not enforce secure boot process.
  18
  19     * M3 JTAG port is closed, R5 JTAG port is open
  20
  21     * DMSC Firewalls are closed, SOC Firewalls are open
  22
  23     * Board configuration need not be signed
  24
  25     * ROM Boot expects a TI signed binary (encryption is optional)
  26
  27     * |sysfw| binary is signed by the TI Private key (TI MPK).
  28       (Refer :ref:`pub_sign_unencrypted_mpk` for more details)
  29
  30 #. **HS-SE (High Security – Security Enforced)**:
  31    Device type after customer keys are programmed. HS-SE devices enforce secure boot.
  32
  33     * M3, R5 JTAG ports are both closed
  34
  35     * DMSC, SOC Firewalls are both closed
  36
  37     * Board configuration needs to be signed with active customer private key (SMPK/BMPK)
  38
  39     * ROM Boot expects a dual signed, encrypted system firmware binary
  40
  41     * |sysfw| binary is encrypted by the TI Encryption key (TI MEK), and signed by the
  42       TI Private key (TI MPK). Customer has to dual sign it with their private key (SMPK/BMPK).
  43       (Refer :ref:`pub_sign_encrypted_mek`)
  44
  45
  46 HS-FS to HS-SE Conversion
  47 =========================
  48
  49 In order to convert a HS-FS device to HS-SE device, one has to program the customer root
  50 key set (optionally backup key set) on the target device, using OTP Keywriter.
  51
  52 Customer key information is encrypted into x509 certificate extension fields. A list of
  53 fields that OTP keywriter supports, can be found :ref:`here <keywriter_supported_fields>`
  54
  55 .. figure:: ../img/sec/key_writer/hsfs_to_hsse_conversion.png
  56   :width: 100%
  57
  58
  59 .. _keywriter_cert_gen_procedure:
  60
  61 Procedure
  62 =========
  63
  64 Following figure illustrates the procedure to be followed to generate the required x509 certifcate for key writing.
  65
  66 .. figure:: ../img/sec/key_writer/key_writer_procedure.png
  67   :width: 100%
  68
  69 #. OEM generates a random 256-bit number to be used as an AES encryption key for
  70    protecting the OTP extension data.
  71
  72 #. The AES-256 key from step 1 is used to encrypt all X509 extension fields,
  73    which require encryption protection.
  74
  75 #. Following X509 extensions are created, using TI FEK (public):
  76
  77    * Encrypting the AES-256 key with TI FEK
  78    * Signing the AES-256 key with the SMPK, and encrypting that with the TI FEK
  79    * (optionally, refer step 6) signing the AES-256 key with the BMPK, and encrypting
  80      that with the TI FEK
  81
  82 #. All of the extensions from steps 1-3 are combined into a X.509 configuration which
  83    is used to generate and sign a certificate with the SMPK.
  84
  85 .. Note::
  86
  87     SMPK Hash. BMPK Hash are computed using SHA-512 Algorithm, for corresponding
  88     Public keys in DER format.
  89
  90 #. This X509 config is sigend using SMPK (priv).
  91
  92 #. (Optional) If the OEM chooses to write BMPK/BMEK fields, X509 config from step 5
  93    needs to be signed using BMPK (priv).
  94
  95 .. _keywriter_supported_fields:
  96
  97 Supported fields
  98 ================
  99
 100 Following fields are supported by the Key writer.
 101
 102 +-------------------+-----------------------------------+---------------------+----------------------+
 103 | Field             | Flashing                          | Mandatory/Optional  | Encoding             |
 104 +===================+===================================+=====================+======================+
 105 | SMPK-Pub          | Part of certificate, not flashed  | Mandatory           |                      |
 106 +-------------------+-----------------------------------+---------------------+----------------------+
 107 | SMPKH             | Flashed                           | Mandatory           |                      |
 108 +-------------------+-----------------------------------+---------------------+----------------------+
 109 | SMPKH-BCH         | Flashed                           | Computed on device  |                      |
 110 +-------------------+-----------------------------------+---------------------+----------------------+
 111 | SMEK              | Flashed                           | Mandatory           |                      |
 112 +-------------------+-----------------------------------+---------------------+----------------------+
 113 | SMEK-BCH          | Flashed                           | Computed on device  |                      |
 114 +-------------------+-----------------------------------+---------------------+----------------------+
 115 | BMPK-Pub          | Part of certificate, not flashed  | Optional            |                      |
 116 +-------------------+-----------------------------------+---------------------+----------------------+
 117 | BMPKH             | Flashed                           | Optional            |                      |
 118 +-------------------+-----------------------------------+---------------------+----------------------+
 119 | BMPKH-BCH         | Flashed                           | Computed on device  |                      |
 120 +-------------------+-----------------------------------+---------------------+----------------------+
 121 | BMEK              | Flashed                           | Optional            |                      |
 122 +-------------------+-----------------------------------+---------------------+----------------------+
 123 | BMEK-BCH          | Flashed                           | Computed on device  |                      |
 124 +-------------------+-----------------------------------+---------------------+----------------------+
 125 | KEYCNT            | Flashed                           | Inferred            |                      |
 126 +-------------------+-----------------------------------+---------------------+----------------------+
 127 | KEYREV            | Flashed                           | Constant            | Set to 1             |
 128 +-------------------+-----------------------------------+---------------------+----------------------+
 129
 130 .. _sysfw_pub_keywr_cert_format:
 131
 132 X509 Configuration Template
 133 ===========================
 134
 135 .. code-block:: bash
 136
 137     [ req ]
 138     distinguished_name = req_distinguished_name
 139     x509_extensions = v3_ca
 140     prompt = no
 141     dirstring_type = nobmp
 142
 143     # This information will be filled by the end user.
 144     # The current data is only a place holder.
 145     # System firmware does not make decisions based
 146     # on the contents of this distinguished name block.
 147     [ req_distinguished_name ]
 148     C = oR
 149     ST = rx
 150     L = gQE843yQV0sag
 151     O = dqhGYAQ2Y4gFfCq0t1yABCYxex9eAxt71f
 152     OU = a87RB35W
 153     CN = x0FSqGTPWbGpuiV
 154     emailAddress = kFp5uGcgWXxcfxi@vsHs9C9qQWGrBs.com
 155
 156     [ v3_ca ]
 157     basicConstraints = CA:true
 158     1.3.6.1.4.1.294.1.64 = ASN1:SEQUENCE:enc_aes_key
 159     1.3.6.1.4.1.294.1.65 = ASN1:SEQUENCE:enc_smpk_signed_aes_key
 160     1.3.6.1.4.1.294.1.66 = ASN1:SEQUENCE:enc_bmpk_signed_aes_key
 161     1.3.6.1.4.1.294.1.67 = ASN1:SEQUENCE:aesenc_smpkh
 162     1.3.6.1.4.1.294.1.68 = ASN1:SEQUENCE:aesenc_smek
 163     1.3.6.1.4.1.294.1.70 = ASN1:SEQUENCE:aesenc_bmpkh
 164     1.3.6.1.4.1.294.1.71 = ASN1:SEQUENCE:aesenc_bmek
 165
 166
 167     [ enc_aes_key ]
 168     # Replace PUT-ENC-AES-KEY with acutal Encrypted AES Key
 169     val = FORMAT:HEX,OCT:PUT_ENC_AES_KEY
 170     size = INTEGER:PUT_SIZE_ENC_AES
 171
 172     [ enc_bmpk_signed_aes_key ]
 173     # Replace PUT-ENC-BMPK-SIGNED-AES-KEY with acutal Encrypted BMPK signed AES Key
 174     val = FORMAT:HEX,OCT:PUT_ENC_BMPK_SIGNED_AES_KEY
 175     size = INTEGER:PUT_SIZE_ENC_BMPK_SIGNED_AES
 176
 177     [ enc_smpk_signed_aes_key ]
 178     # Replace PUT-ENC-SMPK-SIGNED-AES-KEY with acutal Encrypted SMPK signed AES Key
 179     val = FORMAT:HEX,OCT:PUT_ENC_SMPK_SIGNED_AES_KEY
 180     size = INTEGER:PUT_SIZE_ENC_SMPK_SIGNED_AES
 181
 182     [ aesenc_smpkh ]
 183     # Replace PUT-AESENC-SPMKH with acutal Encrypted AES Key
 184     val = FORMAT:HEX,OCT:PUT_AESENC_SMPKH
 185     iv = FORMAT:HEX,OCT:PUT_IV_AESENC_SMPKH
 186     rs = FORMAT:HEX,OCT:PUT_RS_AESENC_SMPKH
 187     size = INTEGER:PUT_SIZE_AESENC_SMPKH
 188
 189     [ aesenc_smek ]
 190     # Replace PUT-AESENC-SMEK with acutal Encrypted AES Key
 191     val = FORMAT:HEX,OCT:PUT_AESENC_SMEK
 192     iv = FORMAT:HEX,OCT:PUT_IV_AESENC_SMEK
 193     rs = FORMAT:HEX,OCT:PUT_RS_AESENC_SMEK
 194     size = INTEGER:PUT_SIZE_AESENC_SMEK
 195
 196     [ aesenc_bmpkh ]
 197     # Replace PUT-AESENC-BMPKH with acutal Encrypted BMPKH
 198     val = FORMAT:HEX,OCT:PUT_AESENC_BMPKH
 199     iv = FORMAT:HEX,OCT:PUT_IV_AESENC_BMPKH
 200     rs = FORMAT:HEX,OCT:PUT_RS_AESENC_BMPKH
 201     size = INTEGER:PUT_SIZE_AESENC_BMPKH
 202
 203     [ aesenc_bmek ]
 204     # Replace PUT-AESENC-BMEK with acutal Encrypted BMEK
 205     val = FORMAT:HEX,OCT:PUT_AESENC_BMEK
 206     iv = FORMAT:HEX,OCT:PUT_IV_AESENC_BMEK
 207     rs = FORMAT:HEX,OCT:PUT_RS_AESENC_BMEK
 208     size = INTEGER:PUT_SIZE_AESENC_BMEK
 209