[processor-sdk/pdk.git] / packages / ti / drv / sciclient / soc / sysfw / binaries / system-firmware-public-documentation / _sources / 2_tisci_msgs / security / sec_cert_format.rst.txt
1 =======================================
2 Security X509 Certificate Documentation
3 =======================================
5 .. _sysfw_x509_ext_doc:
7 Introduction
8 ============
10 This document describes the X509 extensions supported by the X509 parser in System Firmware.
12 .. note::
14 This document is only applicable to HS devices. |sysfw| does not include a
15 X509 parser on GP devices.
17 References
18 ==========
20 1. ISO 8824-1 | ITU-T X.680 (08/2015): Information technology - Abstract Syntax
21 Notation One (ASN.1): Specification of basic notation,
22 http://handle.itu.int/11.1002/1000/12479
23 2. ISO 8825-1 | ITU-T X.690 (09/2015): Information technology - ASN.1 encoding
24 rules: Specification of Basic Encoding Rules (BER), Canonical Encoding Rules
25 (CER) and Distinguished Encoding Rules (DER)
26 http://handle.itu.int/11.1002/1000/12483
27 3. ISO/IEC 9594-8 | ITU-T X.509 (10/2016): Information technology - Open Systems
28 Interconnection - The Directory: Public-key and attribute certificate
29 frameworks
30 http://handle.itu.int/11.1002/1000/13031
31 4. :doc:`PROC_BOOT`
34 .. _sysfw_x509_ext_summary:
36 Extensions
37 ==========
39 The following X509 extensions are supported by |sysfw|.
41 +--------------------------------------+-------------------------------------------------+-----------------------+
42 | Extension Name | Purpose | OID |
43 +======================================+=================================================+=======================+
44 | :ref:`sysfw_boot_ext` | Provide boot information | 1.3.6.1.4.1.294.1.33 |
45 +--------------------------------------+-------------------------------------------------+-----------------------+
46 | :ref:`sysfw_image_integrity_ext` | Image hash and length | 1.3.6.1.4.1.294.1.34 |
47 +--------------------------------------+-------------------------------------------------+-----------------------+
48 | :ref:`sysfw_swrev_ext` | revision of binary for anti-rollback | 1.3.6.1.4.1.294.1.3 |
49 +--------------------------------------+-------------------------------------------------+-----------------------+
50 | :ref:`sysfw_load_ext` | Provide load information | 1.3.6.1.4.1.294.1.35 |
51 +--------------------------------------+-------------------------------------------------+-----------------------+
52 | :ref:`sysfw_debug_ext` | To unlock debug port | 1.3.6.1.4.1.294.1.8 |
53 +--------------------------------------+-------------------------------------------------+-----------------------+
54 | :ref:`sysfw_encryption_ext` | Encryption extension | 1.3.6.1.4.1.294.1.4 |
55 +--------------------------------------+-------------------------------------------------+-----------------------+
56 | :ref:`sysfw_hs_bcfg_ext` | HS Boardcfg extension | 1.3.6.1.4.1.294.1.36 |
57 +--------------------------------------+-------------------------------------------------+-----------------------+
58 | :ref:`keywr_enc_aes_ext` | Keywriter Encrypted AES extension | 1.3.6.1.4.1.294.1.64 |
59 +--------------------------------------+-------------------------------------------------+-----------------------+
60 | :ref:`keywr_enc_smpk_sign_aes_ext` | Keywriter Encrypted SMPK Signed AES extension | 1.3.6.1.4.1.294.1.65 |
61 +--------------------------------------+-------------------------------------------------+-----------------------+
62 | :ref:`keywr_enc_bmpk_sign_aes_ext` | Keywriter Encrypted BMPK Signed AES extension | 1.3.6.1.4.1.294.1.66 |
63 +--------------------------------------+-------------------------------------------------+-----------------------+
64 | :ref:`keywr_aes_enc_smpkh` | Keywriter AES Encrypted SMPKH | 1.3.6.1.4.1.294.1.67 |
65 +--------------------------------------+-------------------------------------------------+-----------------------+
66 | :ref:`keywr_aes_enc_smek` | Keywriter AES Encrypted SMEK | 1.3.6.1.4.1.294.1.68 |
67 +--------------------------------------+-------------------------------------------------+-----------------------+
68 | :ref:`keywr_aes_enc_smpk_opt` | Keywriter AES Encrypted SMPK Options | 1.3.6.1.4.1.294.1.69 |
69 +--------------------------------------+-------------------------------------------------+-----------------------+
70 | :ref:`keywr_aes_enc_bmpkh` | Keywriter AES Encrypted BMPKH | 1.3.6.1.4.1.294.1.70 |
71 +--------------------------------------+-------------------------------------------------+-----------------------+
72 | :ref:`keywr_aes_enc_bmek` | Keywriter AES Encrypted BMEK | 1.3.6.1.4.1.294.1.71 |
73 +--------------------------------------+-------------------------------------------------+-----------------------+
74 | :ref:`keywr_aes_enc_bmpk_opt` | Keywriter AES Encrypted BMPK Options | 1.3.6.1.4.1.294.1.72 |
75 +--------------------------------------+-------------------------------------------------+-----------------------+
76 | :ref:`keywr_aes_enc_user_otp` | Keywriter AES Encrypted user OTP | 1.3.6.1.4.1.294.1.73 |
77 +--------------------------------------+-------------------------------------------------+-----------------------+
78 | :ref:`keywr_aes_enc_keyrev` | Keywriter AES Encrypted key revision | 1.3.6.1.4.1.294.1.74 |
79 +--------------------------------------+-------------------------------------------------+-----------------------+
80 | :ref:`keywr_aes_enc_swrev` | Keywriter AES Encrypted software revision | 1.3.6.1.4.1.294.1.75 |
81 +--------------------------------------+-------------------------------------------------+-----------------------+
82 | :ref:`keywr_aes_enc_msv` | Keywriter AES Encrypted MSV | 1.3.6.1.4.1.294.1.76 |
83 +--------------------------------------+-------------------------------------------------+-----------------------+
85 .. _sysfw_boot_ext:
87 |sysfw| Boot Extension
88 ----------------------
90 This extension adds support for booting various cores on a K3 SOC. It is
91 identified by the OID **1.3.6.1.4.1.294.1.33**. The structure of the field is
92 shown below in ASN.1 notation.
94 ::
96 SYSFW-Boot := SEQUENCE
97 {
98 bootCore INTEGER, -- indicates the core in the device that needs to be booted
99 -- with the image accompanying this certificate.
100 configFlags_set INTEGER, -- Configuration options for the core being booted.
101 -- flags to set
102 configFlags_clr INTEGER, -- Configuration options for the core being booted
103 -- flags to clear
104 resetVec OCTET STRING, -- Location of reset vector for the core.
106 fieldValid INTEGER -- indicates which of the reserved fields in the extension are
107 -- valid
108 rsvd1 INTEGER, -- reserved field for future use
109 rsvd2 INTEGER, -- reserved field for future use
110 rsvd3 INTEGER, -- reserved field for future use
111 }
113 The boot extension is decoded into the below structure.
115 ::
117 struct sec_boot_ctrl {
118 u32 bootCore;
119 u32 configFlags_set;
120 u32 configFlags_clr;
121 u64 resetVec;
122 }
124 The reserved fields are for future use and are not decoded currently.
127 Populating the certificate fields
128 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
130 For an example, please refer to the section ``[ sysfw_boot_seq ]`` in :ref:`sysfw_x509_template_example`.
132 1. ``bootCore`` should be initialized to the Core ID of the targeted core.
133 Core ID should be obtained from the SOC data. e.g. For booting a
134 core with ID ``0x20``, the relevant line in the X509 template is
136 ::
138 [ boot_seq ]
139 bootCore = INTEGER:0x20
141 2. ``configFlags_set``
143 - This is a 32 bit field that indicates core specific flags that need
144 to be set before booting the core. The representation is big endian.
146 3. ``configFlags_clr``
148 - This is a 32 bit field that indicates core specific flags that need
149 to be cleared before booting core. The representation is big endian.
151 Please refer to the SOC and core specific documentation on the supported
152 flags. The flags are passed to
153 :ref:`set_processor_config <proc-boot-set-processor-configuration>` API as
154 is. Please ensure that the flags set or cleared are valid according to the
155 API.
157 4. ``resetVec``
159 - This is a 64 bit field indicating the address of the reset vector
160 that needs to be programmed. The representation is big endian.
162 .. _sysfw_image_integrity_ext:
164 |sysfw| Image Integrity Extension
165 ---------------------------------
167 This extension adds support for specifying a hash and size of the accompanying
168 payload. It is identified by the OID **1.3.6.1.4.1.294.1.34**. The structure of
169 the field is shown below in ASN.1 notation.
171 ::
173 SYSFW-INTEGRITY := SEQUENCE
174 {
175 shaType OID, -- indicates OID of the hash used. Must always be set to SHA2-512
176 -- OID:2.16.840.1.101.3.4.2.3
177 shaValue OCTET STRING, -- SHA2-512 value of the payload
178 imageSize INTEGER, -- Size of the image in bytes. This will be amount of data
179 -- used when checking the image integrity, copying the image
180 -- to its destination or when decrypting the image.
181 }
184 .. _sysfw_swrev_ext:
186 |sysfw| Software Revision Extension
187 -----------------------------------
189 |sysfw| reuses the Software Revision extension/OID as defined by ROM as no
190 additional information is required. This is identified by OID
191 **1.3.6.1.4.1.294.1.3**.
193 ::
195 SYSFW-SWREV:= SEQUENCE
196 {
197 swrev INTEGER -- 32 bit value indicating the revision of the binary
198 }
201 .. _sysfw_load_ext:
203 |sysfw| Load Extension
204 ----------------------
206 |sysfw| uses the Load extension to determine where the image is loaded
207 as part of authentication. The load extension is identified by OID **1.3.6.1.4.1.294.1.35**. This is a new extension defined by |sysfw|.
209 ::
211 SYSFW-LOAD := SEQUENCE
212 {
213 destAddr OCTET STRING, -- Address to which the image accompanying this certificate
214 -- needs to be copied.
215 auth_in_place INTEGER -- Controls if/how the authenticated binary is copied to a different
216 -- location. See below for more information.
217 }
219 The load extension is decoded into the below structure.
221 ::
223 struct ti_load_info {
224 u64 destAddr;
225 u8 auth_in_place;
226 };
228 Populating the certificate fields
229 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
231 1. ``destAddr``
233 - This is a 64 bit field indicating the address to which the data
234 needs to be copied. The representation is big endian.
236 2. ``auth_in_place``
238 - This is an integer field used to indicate whether the binary should be copied
239 to the specified load address during authentication. The valid values for this
240 field and their interpretation are described below.
242 +----------+-----------------------------------------------------------------+
243 | Value | Action |
244 +==========+=================================================================+
245 | 0 | Normal operation. Binary is copied to load address. |
246 +----------+-----------------------------------------------------------------+
247 | 1 | In place operation. Binary is not moved. |
248 +----------+-----------------------------------------------------------------+
249 | 2 | In place operation variant. Binary is moved to the beginning of |
250 | | the buffer i.e. binary now starts at the location where the |
251 | | certificate started |
252 +----------+-----------------------------------------------------------------+
253 | Any | invalid operation |
254 | other | |
255 | value | |
256 +----------+-----------------------------------------------------------------+
258 .. _sysfw_encryption_ext:
260 |sysfw| Encryption Extension
261 ----------------------------
263 |sysfw| reuses the Encryption extension/OID as defined by ROM as no
264 additional information is required. This is identified by OID
265 **1.3.6.1.4.1.294.1.4**.
267 ::
269 SYSFW-ENCRYPT := SEQUENCE
270 {
271 initalVector OCTET STRING,
272 randomString OCTET STRING,
273 iterationCnt INTEGER,
274 salt OCTET STRING
275 }
277 The encryption extension is decoded into the following data structure.
279 .. code-block:: c
281 struct ti_enc_info {
282 u8 initialVector[16];
283 u8 randomString[32];
284 u8 iterationCnt;
285 u8 salt[32];
286 };
288 Populating the certificate fields
289 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
291 1. ``initialVector``
293 - This is the 16 byte initialization vector to be used in AES-CBC
294 decryption.
296 2. ``randomString``
298 - This field indicates the random 32 byte string that was appended to the
299 binary before encrypting the combined binary. |sysfw| will compare the last
300 32 bytes of the decryption output against the ``randomString`` field from
301 the X509 certificate to verify the success of decryption operation.
303 3. ``iterationCnt``
305 - This field is reserved and must be initialized to zero.
307 4. ``salt``
309 - This field is 32 bytes long. It is reserved and must be initialized to zero.
311 .. note::
313 |sysfw| always loads the binary to the location specified by :ref:`sysfw_load_ext`
314 before performing in-place decryption at the loaded location.
317 .. _sysfw_debug_ext:
319 |sysfw| Debug Extension
320 -----------------------
322 .. note::
324 This extension is not yet finalized.
326 The custom extension field used for debug control is identified by the OID
327 **1.3.6.1.4.1.294.1.8**. The structure of the field is shown below in
328 ASN.1 notation.
330 ::
332 UID-Debug ::= SEQUENCE
333 {
334 uid OCTET STRING, -- unique ID of the device for which this certificate applies
335 debugCtrl INTEGER, -- debug control information
336 coreDbgEn INTEGER, -- Core IDs for which debug must be enabled
337 coreDbgSecEn INTEGER, -- Core IDs for which secure debug must be enabled
338 }
340 The debug control data is decoded as a structure below:
342 ::
344 struct sdbg_debug_ctrl {
345 u16 debug_priv_level;
346 u16 reserved;
347 u8 debug_core_sel[MAX_CPU_CORES];
348 u8 sec_debug_core_sel[MAX_CPU_CORES];
349 }
351 The table below shows the way **UID-Debug** fields are decoded into **struct sdbg_debug_ctrl**.
353 +------------------------+----------------------------------------------------------+
354 | sdbg_debug_ctrl member | X.509 certificate debug extension field |
355 +========================+==========================================================+
356 | debug_priv_level |debugCtrl field is decoded as a u32 value and the lower 16|
357 | |bit value is picked up |
358 +------------------------+----------------------------------------------------------+
359 | reserved |debugCtrl field is decoded as a u32 value and the upper 16|
360 | |bit value is picked up |
361 +------------------------+----------------------------------------------------------+
362 | debug_core_sel |coreDbgEn field is decoded as an array of u8 values of |
363 | |processor IDs for which non-secure debug should be |
364 | |enabled |
365 +------------------------+----------------------------------------------------------+
366 | sec_debug_core_sel |coreDbgSecEn field is decoded as an array of u8 values of |
367 | |processor IDs for which secure debug should be enabled |
368 +------------------------+----------------------------------------------------------+
371 .. _sysfw_x509_ext_doc_debug_levels_table:
373 The following table shows the enumeration of values for **debug_priv_level**:
375 +-------------------+-------+-------------------------------------------------------+
376 | Enumeration name | Value | Meaning |
377 +===================+=======+=======================================================+
378 | DEBUG_DISABLE | 0 | Disable debug |
379 +-------------------+-------+-------------------------------------------------------+
380 | DEBUG_PRESERVE | 1 | Preserve current setting by locking registers |
381 +-------------------+-------+-------------------------------------------------------+
382 | DEBUG_PUBLIC | 2 | Enable debug at public (non-secure) user and |
383 | | | privileged level |
384 +-------------------+-------+-------------------------------------------------------+
385 | DEBUG_PUBLIC_USER | 3 | Enable debug at public (non-secure) user level only |
386 +-------------------+-------+-------------------------------------------------------+
387 | DEBUG_FULL | 4 | Enable full debug (both secure and non-secure |
388 | | | privileged and user levels) |
389 +-------------------+-------+-------------------------------------------------------+
390 | DEBUG_SECURE_USER | 5 | Enable debug for both secure and non-secure at user |
391 | | | level only |
392 +-------------------+-------+-------------------------------------------------------+
394 For an example, please refer to the section ``[ debug ]`` in :ref:`sysfw_x509_template_example`.
396 .. _sysfw_hs_bcfg_ext:
398 |sysfw| HS Board Configuration Extension
399 -------------------------------------------------
401 |sysfw| extends the Encryption extension/OID as defined by ROM for the purpose
402 of authenticating the board configurations on HS devices. The hashes of the 4
403 board configuration blobs
405 1. Core board configuration
406 2. PM board configurations
407 3. RM board configuration
408 4. Encrypted Security board configuration
410 and the encryption parameters of the security board configuration are encoded in
411 the board configuration extension of the |sysfw| outer certificate . This
412 extension is identified by OID **1.3.6.1.4.1.294.1.36**.
414 ::
416 SYSFW-HS-BCFG:= SEQUENCE
417 {
418 initalVector OCTET STRING,
419 randomString OCTET STRING,
420 iterationCnt INTEGER,
421 salt OCTET STRING,
422 secBoardCfgHash OCTET STRING,
423 secBoardCfgVer INTEGER,
424 pmBoardCfgHash OCTET STRING,
425 rmBoardCfgHash OCTET STRING
426 boardCfgHash OCTET STRING
427 }
429 The extension is decoded into the following data structure.
431 .. code-block:: c
433 struct ti_bcfg_info {
434 u8 initialVector[16];
435 u8 randomString[32];
436 u8 iterationCnt;
437 u8 salt[32];
438 u8 secBoardCfgHash[64];
439 u8 secBoardCfgVer;
440 u8 pmBoardCfgHash[64];
441 u8 rmBoardCfgHash[64];
442 u8 boardCfgHash[64];
443 };
445 Populating the certificate fields
446 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
448 1. ``initialVector``
450 - This is the 16 byte initialization vector to be used in AES-CBC
451 decryption.
453 2. ``randomString``
455 - This field indicates the random 32 byte string that was appended to the
456 board configuration binary before encrypting the combined binary. |sysfw|
457 will compare the last 32 bytes of the decryption output against the
458 ``randomString`` field from the X509 certificate to verify the success of
459 decryption operation.
461 3. ``iterationCnt``
463 - This field is reserved and must be initialized to zero.
465 4. ``salt``
467 - This field is 32 bytes long. It is reserved and must be initialized to
468 zero.
470 5. ``secBoardCfgHash``
472 - This is a 64 byte field containing the SHA2-512 hash of the encrypted |sec_bcfg|.
474 6. ``secBoardCfgVer``
476 - This field indicates the version of security board configuration and must be initialized
477 to zero.
479 7. ``pmBoardCfgHash``
481 - This is a 64 byte field containing the SHA2-512 hash of the PM board configuration.
483 8. ``rmBoardCfgHash``
485 - This is a 64 byte field containing the SHA2-512 hash of the RM board configuration.
487 8. ``boardCfgHash``
489 - This is a 64 byte field containing the SHA2-512 hash of the main board configuration
490 structure.
493 .. _keywr_enc_aes_ext:
495 |sysfw| Keywriter Encrypted AES extension
496 -------------------------------------------------
498 This extension has the information about TIFEK(public) encrypted AES-256 key (random key,
499 chosen by customer for keywriter). It is identified by the OID **1.3.6.1.4.1.294.1.64**.
500 The structure of the fields is shown below in ASN.1 notation.
502 ::
504 KEYWR-ENC-AES := SEQUENCE
505 {
506 val OCTET STRING, -- TIFEK(pub) encrypted AES-256 key chosen by the user.
507 size INTEGER -- size
508 }
511 .. code-block:: c
513 struct keywr_enc_aes {
514 u8 val[512];
515 u32 size;
516 };
518 .. _keywr_enc_smpk_sign_aes_ext:
520 |sysfw| Keywriter Encrypted SMPK Signed AES extension
521 -------------------------------------------------------
523 This extension has the information about TIFEK(public) encrypted, SMPK(priv) signed
524 AES-256 key (random key, chosen by customer for keywriter). It is identified by the
525 OID **1.3.6.1.4.1.294.1.65**. The structure of the fields is shown below in ASN.1 notation.
527 ::
529 KEYWR-ENC-SMPK-SIGN-AES := SEQUENCE
530 {
531 val OCTET STRING, -- TIFEK(pub) encrypted, SMPK(priv) signed AES-256 key chosen by the user.
532 size INTEGER -- size
533 }
535 .. code-block:: c
537 struct keywr_enc_smpk_sign_aes {
538 u8 val[512];
539 u32 size;
540 };
543 .. _keywr_enc_bmpk_sign_aes_ext:
545 |sysfw| Keywriter Encrypted BMPK Signed AES extension
546 ------------------------------------------------------
548 This extension has the information about TIFEK(public) encrypted, BMPK(priv) signed AES-256 key (random key,
549 chosen by customer for keywriter). It is identified by the OID **1.3.6.1.4.1.294.1.66**.
550 The structure of the fields is shown below in ASN.1 notation.
552 ::
554 KEYWR-ENC-BMPK-SIGN-AES := SEQUENCE
555 {
556 val OCTET STRING, -- TIFEK(pub) encrypted, BMPK(priv) signed AES-256 key chosen by the user.
557 size INTEGER -- size
558 }
560 .. code-block:: c
562 struct keywr_enc_bmpk_sign_aes {
563 u8 val[512];
564 u32 size;
565 };
568 .. _keywr_aes_enc_smpkh:
570 |sysfw| Keywriter AES Encrypted SMPKH
571 ------------------------------------------------------
573 This extension has the information about AES-256 key encrypted SMPKH (SHA-512 used for hashing).
574 It is identified by the OID **1.3.6.1.4.1.294.1.67**
575 The structure of the fields is shown below in ASN.1 notation.
577 ::
579 KEYWR-AES-ENC-SMPKH := SEQUENCE
580 {
581 val OCTET STRING, -- AES-256 key encrypted SMPKH (SHA-512 used for hashing)
582 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
583 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
584 size INTEGER -- size
585 }
587 .. code-block:: c
589 struct keywr_aes_enc_smpkh {
590 u8 val[64];
591 u8 iv[16];
592 u8 rs[32];
593 u32 size;
594 };
597 .. _keywr_aes_enc_smek:
599 |sysfw| Keywriter AES Encrypted SMEK
600 ------------------------------------------------------
602 This extension has the information about AES-256 key encrypted SMEK.
603 It is identified by the OID **1.3.6.1.4.1.294.1.68**
604 The structure of the fields is shown below in ASN.1 notation.
606 ::
608 KEYWR-AES-ENC-SMEK := SEQUENCE
609 {
610 val OCTET STRING, -- AES-256 key encrypted SMEK
611 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
612 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
613 size INTEGER -- size
614 }
616 .. code-block:: c
618 struct keywr_aes_enc_smek {
619 u8 val[64];
620 u8 iv[16];
621 u8 rs[32];
622 u32 size;
623 };
626 .. _keywr_aes_enc_smpk_opt:
628 |sysfw| Keywriter AES Encrypted SMPK Options
629 ------------------------------------------------------
631 This extension has the information about AES-256 key encrypted SMPK Options
632 It is identified by the OID **1.3.6.1.4.1.294.1.69**
633 The structure of the fields is shown below in ASN.1 notation.
634 This is not currently supported by OTP Keywriter
636 ::
638 KEYWR-AES-ENC-SMPK-OPT := SEQUENCE
639 {
640 val OCTET STRING, -- AES-256 key encrypted SMPK Options
641 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
642 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
643 size INTEGER -- size
644 }
646 .. code-block:: c
648 struct keywr_aes_enc_smpk_opt {
649 u8 val[64];
650 u8 iv[16];
651 u8 rs[32];
652 u32 size;
653 };
655 .. _keywr_aes_enc_bmpkh:
657 |sysfw| Keywriter AES Encrypted BMPKH
658 ------------------------------------------------------
660 This extension has the information about AES-256 key encrypted BMPKH (SHA-512 used for hashing).
661 It is identified by the OID **1.3.6.1.4.1.294.1.70**
662 The structure of the fields is shown below in ASN.1 notation.
664 ::
666 KEYWR-AES-ENC-BMPKH := SEQUENCE
667 {
668 val OCTET STRING, -- AES-256 key encrypted BMPKH (SHA-512 used for hashing)
669 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
670 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
671 size INTEGER -- size
672 }
674 .. code-block:: c
676 struct keywr_aes_enc_bmpkh {
677 u8 val[64];
678 u8 iv[16];
679 u8 rs[32];
680 u32 size;
681 };
684 .. _keywr_aes_enc_bmek:
686 |sysfw| Keywriter AES Encrypted BMEK
687 ------------------------------------------------------
689 This extension has the information about AES-256 key encrypted BMEK.
690 It is identified by the OID **1.3.6.1.4.1.294.1.71**
691 The structure of the fields is shown below in ASN.1 notation.
693 ::
695 KEYWR-AES-ENC-BMEK := SEQUENCE
696 {
697 val OCTET STRING, -- AES-256 key encrypted BMEK
698 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
699 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
700 size INTEGER -- size
701 }
703 .. code-block:: c
705 struct keywr_aes_enc_bmek {
706 u8 val[64];
707 u8 iv[16];
708 u8 rs[32];
709 u32 size;
710 };
713 .. _keywr_aes_enc_bmpk_opt:
715 |sysfw| Keywriter AES Encrypted BMPK Options
716 ------------------------------------------------------
718 This extension has the information about AES-256 key encrypted BMPK Options
719 It is identified by the OID **1.3.6.1.4.1.294.1.72**
720 The structure of the fields is shown below in ASN.1 notation.
721 This is not currently supported by OTP Keywriter
723 ::
725 KEYWR-AES-ENC-BMPK-OPT := SEQUENCE
726 {
727 val OCTET STRING, -- AES-256 key encrypted SMPK Options
728 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
729 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
730 size INTEGER -- size
731 }
733 .. code-block:: c
735 struct keywr_aes_enc_bmpk_opt {
736 u8 val[64];
737 u8 iv[16];
738 u8 rs[32];
739 u32 size;
740 };
743 .. _keywr_aes_enc_user_otp:
745 |sysfw| Keywriter AES Encrypted user OTP
746 ------------------------------------------------------
748 This extension has the information about AES-256 key encrypted extended OTP
749 It is identified by the OID **1.3.6.1.4.1.294.1.73**
750 The structure of the fields is shown below in ASN.1 notation.
751 This is not currently supported by OTP Keywriter
753 ::
755 KEYWR-AES-ENC-USER-OTP := SEQUENCE
756 {
757 val OCTET STRING, -- Extended OTP in octet string format
758 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
759 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
760 size INTEGER -- size
761 }
763 .. code-block:: c
765 struct keywr_aes_enc_user_otp {
766 u8 val[64];
767 u8 iv[16];
768 u8 rs[32];
769 u32 size;
770 };
773 .. _keywr_aes_enc_keyrev:
775 |sysfw| Keywriter AES Encrypted key revision
776 ------------------------------------------------------
778 This extension has the information about AES-256 key encrypted Keyrevision.
779 By default, keyrevision should be set to 1. If it is set to 2, BMPK and BMEK will be used
780 instead of SMPK and SMEK. It is identified by the OID **1.3.6.1.4.1.294.1.74**.
781 The structure of the fields is shown below in ASN.1 notation.
782 This is not currently supported by OTP Keywriter
784 ::
786 KEYWR-AES-ENC-KEYREV := SEQUENCE
787 {
788 val OCTET STRING, -- AES-256 key encrypted Keyrev
789 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
790 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
791 size INTEGER -- size
792 }
794 .. code-block:: c
796 struct keywr_aes_enc_keyrev {
797 u8 val[64];
798 u8 iv[16];
799 u8 rs[32];
800 u32 size;
801 };
804 .. _keywr_aes_enc_swrev:
806 |sysfw| Keywriter AES Encrypted software revision
807 ------------------------------------------------------
809 This extension has the information about AES-256 key encrypted Software revision.
810 It is identified by the OID **1.3.6.1.4.1.294.1.75**
811 The structure of the fields is shown below in ASN.1 notation.
812 This is not currently supported by OTP Keywriter
814 ::
816 KEYWR-AES-ENC-SWREV := SEQUENCE
817 {
818 val OCTET STRING, -- AES-256 key encrypted Keyrev
819 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
820 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
821 size INTEGER -- size
822 }
824 .. code-block:: c
826 struct keywr_aes_enc_swrev {
827 u8 val[64];
828 u8 iv[16];
829 u8 rs[32];
830 u32 size;
831 };
834 .. _keywr_aes_enc_msv:
836 |sysfw| Keywriter AES Encrypted MSV
837 ------------------------------------------------------
839 This extension has the information about AES-256 key encrypted MSV
840 It is identified by the OID **1.3.6.1.4.1.294.1.76**
841 The structure of the fields is shown below in ASN.1 notation.
842 This is not currently supported by OTP Keywriter
844 ::
846 KEYWR-AES-ENC-MSV := SEQUENCE
847 {
848 val OCTET STRING, -- AES-256 key encrypted MSV
849 iv OCTET STRING, -- Intitial Value used in AES-256-CBC encryption, 128 bits
850 rs OCTET STRING, -- Random String used in AES-256-CBC encryption, 256 bits
851 size INTEGER -- size
852 }
854 .. code-block:: c
856 struct keywr_aes_enc_msv {
857 u8 val[64];
858 u8 iv[16];
859 u8 rs[32];
860 u32 size;
861 };
863 .. _sysfw_x509_template_example:
865 Sample x509 template
866 ---------------------
868 .. note::
870 The template below shows all the X509 extensions supported by the |sysfw|
871 ASN1 parser. Depending on the usecase, the certificate may contain only a few
872 of these extensions.
874 - For performing JTAG unlock, only Software revision (``swrv``) and
875 Debug(``debug``) extensions are required.
876 - For authenticating a binary, only the Load (``sysfw_image_load``) and
877 Image integrity (``sysfw_image_integrity``) extensions are required.
879 .. note::
881 The data in the ``req_distinguished_name`` section is random to indicates
883 1. |sysfw| does not process the information in the section.
884 2. This needs to be updated by the user to reflect his information.
887 .. code-block :: bash
889 [ req ]
890 distinguished_name = req_distinguished_name
891 x509_extensions = v3_ca
892 prompt = no
894 dirstring_type = nobmp
896 # This information will be filled by the end user.
897 # The current data is only a place holder.
898 # System firmware does not make decisions based
899 # on the contents of this distinguished name block.
900 [ req_distinguished_name ]
901 C = oR
902 ST = rx
903 L = gQE843yQV0sag
904 O = dqhGYAQ2Y4gFfCq0t1yABCYxex9eAxt71f
905 OU = a87RB35W
906 CN = x0FSqGTPWbGpuiV
907 emailAddress = kFp5uGcgWXxcfxi@vsHs9C9qQWGrBs.com
909 [ v3_ca ]
910 basicConstraints = CA:true
911 1.3.6.1.4.1.294.1.3=ASN1:SEQUENCE:swrv
912 1.3.6.1.4.1.294.1.4=ASN1:SEQUENCE:encryption
913 1.3.6.1.4.1.294.1.8=ASN1:SEQUENCE:debug
914 1.3.6.1.4.1.294.1.36=ASN1:SEQUENCE:sysfw_hs_boardcfg
915 1.3.6.1.4.1.294.1.33=ASN1:SEQUENCE:sysfw_boot_seq
916 1.3.6.1.4.1.294.1.34=ASN1:SEQUENCE:sysfw_image_integrity
917 1.3.6.1.4.1.294.1.35=ASN1:SEQUENCE:sysfw_image_load
918 1.3.6.1.4.1.294.1.36=ASN1:SEQUENCE:sysfw_hs_boardcfg
920 [ sysfw_boot_seq ]
921 bootCore = INTEGER:0x20
922 bootCoreOpts_set = INTEGER:0x00000000
923 bootCoreOpts_clr = INTEGER:0x00000000
924 resetVec = FORMAT:HEX,OCT:41c02100
925 flagsValid = INTEGER:0x00
926 rsvd1 = INTEGER:0x00
927 rsdv2 = INTEGER:0x00
928 rsdv3 = INTEGER:0x00
930 [ sysfw_image_integrity ]
931 shaType = OID:2.16.840.1.101.3.4.2.3
932 shaValue = FORMAT:HEX,OCT:TEST_IMAGE_SHA512
933 # Replace TEST_IMAGE_LENGTH with actual image length
934 imageSize = INTEGER:TEST_IMAGE_LENGTH
936 [ sysfw_image_load ]
937 destAddr = FORMAT:HEX,OCT:41c02100
938 authInPlace = INTEGER:0
940 [ swrv ]
941 swrv = INTEGER:0
943 [ debug ]
944 debugUID = FORMAT:HEX,OCT:0000000000000000000000000000000000000000000000000000000000000000
945 debugType = INTEGER:0x00000004
946 coreDbgEn = INTEGER:0x20210102
947 coreDbgSecEn = INTEGER:0x2223
949 [ encryption ]
950 initalVector = FORMAT:HEX,OCT:TEST_IMAGE_ENC_IV
951 randomString = FORMAT:HEX,OCT:TEST_IMAGE_ENC_RS
952 iterationCnt = INTEGER:TEST_IMAGE_KEY_DERIVE_INDEX
953 salt = FORMAT:HEX,OCT:TEST_IMAGE_KEY_DERIVE_SALT
955 [ sysfw_hs_boardcfg ]
956 initalVector = FORMAT:HEX,OCT:SEC_BCFG_ENC_IV
957 randomString = FORMAT:HEX,OCT:SEC_BCFG_ENC_RS
958 iterationCnt = INTEGER:SEC_BCFG_KEY_DERIVE_INDEX
959 salt = FORMAT:HEX,OCT:SEC_BCFG_KEY_DERIVE_SALT
960 secBoardcfgHash = FORMAT:HEX,OCT:SEC_BCFG_HASH
961 secBoardcfgVer = INTEGER:SEC_BCFG_VER
962 pmBoardcfgHash = FORMAT:HEX,OCT:PM_BCFG_HASH
963 rmBoardcfgHash = FORMAT:HEX,OCT:RM_BCFG_HASH
964 boardcfgHash = FORMAT:HEX,OCT:BCFG_HASH