Registered User m (Undo revision 95478 by Registered User (-)) Tag: Undo |
Registered User m (cleanup (to avoid duplicating information)) Tag: 2017 source edit |
||
(3 intermediate revisions by one other user not shown) | |||
Line 1: | Line 1: | ||
<noinclude>{{ApplicableFor | <noinclude>{{ApplicableFor | ||
|MPUs list=STM32MP13x, STM32MP15x | |MPUs list=STM32MP13x, STM32MP15x, STM32MP25x, | ||
|MPUs checklist=STM32MP13x,STM32MP15x | |MPUs checklist=STM32MP13x,STM32MP15x, STM32MP25x, | ||
}}</noinclude> | }}</noinclude> | ||
==Article purpose== | ==Article purpose== | ||
Line 30: | Line 30: | ||
Both certificates contain a non-volatile counter value that can be used for anti-rollback protection. | Both certificates contain a non-volatile counter value that can be used for anti-rollback protection. | ||
TF-A BL2 implements a default certificate chain to describe the PKI topology defined in {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}}. It is used by the {{DocSource | domain=TF-A | path=components/fconf/index.html | text=firmware configuration framework}} to register into TF-A BL2 the chaining implementation based on generic CoT DTSI file. It describes the chain of trust following the specified {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}. STM32MPU platforms use a specific STM32MPU device tree | TF-A BL2 implements a default certificate chain to describe the PKI topology defined in {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}}. It is used by the {{DocSource | domain=TF-A | path=components/fconf/index.html | text=firmware configuration framework}} to register into TF-A BL2 the chaining implementation based on generic CoT DTSI file. It describes the chain of trust following the specified {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}. STM32MPU platforms use a specific STM32MPU device tree which describes a specific topology for ST needs (see [[#STM32_MPU_implementation| STM32 MPU implementation chapter]]). Based on this example, the PKI topology can be customized by customers. | ||
Once generated, all the certificates are part of the [[How_to_configure_TF-A_FIP|FIP]], which are updatable independently. | Once generated, all the certificates are part of the [[How_to_configure_TF-A_FIP|FIP]], which are updatable independently. | ||
Line 49: | Line 49: | ||
* the Crypto Module(CM) with a dedicated Cryptographic Library (CL). | * the Crypto Module(CM) with a dedicated Cryptographic Library (CL). | ||
== STM32 MPU implementation== | == STM32 MPU implementation == | ||
=== CoT === | === CoT === | ||
STM32 MPU is based on the standard Arm<sup>®</sup>TBBR PKI implementation. STM32MPU defines a specific {{CodeSource | TF-A | fdts/stm32mp1-cot-descriptors.dtsi}} in the TF-A BL2 device tree board file. | STM32 MPU is based on the standard Arm<sup>®</sup>TBBR PKI implementation. STM32MPU defines a specific {{CodeSource | TF-A | fdts/stm32mp1-cot-descriptors.dtsi}} on {{MicroprocessorDevice | device=1}} and {{CodeSource | TF-A | fdts/stm32mp2-cot-descriptors.dtsi}} on {{MicroprocessorDevice | device=2}} in the TF-A BL2 device tree board file. | ||
<div class="res-img"> | <div class="res-img"> | ||
Line 60: | Line 60: | ||
==== Define a custom CoT ==== | ==== Define a custom CoT ==== | ||
It is possible to update the CoT by changing the chain of certificate. This must be done accordingly at: | It is possible to update the CoT by changing the chain of certificate. This must be done accordingly at: | ||
* Certificate creation tool platform level {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_tbb_cert.c}}. | * Certificate creation tool platform level {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_tbb_cert.c}} on {{MicroprocessorDevice | device=1}} and {{CodeSource | TF-A | plat/st/stm32mp2/stm32mp2_tbb_cert.c}} on {{MicroprocessorDevice | device=2}}. | ||
* Custom device tree descriptor level {{CodeSource | TF-A | fdts/stm32mp1-cot-descriptors.dtsi}} | * Custom device tree descriptor level {{CodeSource | TF-A | fdts/stm32mp1-cot-descriptors.dtsi}} on {{MicroprocessorDevice | device=1}} and {{CodeSource | TF-A | fdts/stm32mp2-cot-descriptors.dtsi}} on {{MicroprocessorDevice | device=2}} following the {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}. | ||
=== RoT === | === RoT === | ||
The Root of Trust Public Key ({{Highlight|ROTPK}}) used as reference for the chain of trust.<br> | The Root of Trust Public Key ({{Highlight|ROTPK}}) used as reference for the chain of trust.<br> | ||
The | The STM32 MPU platform <code>plat_get_rotpk_info</code> implementation is made in : {{CodeSource | TF-A | plat/st/common/stm32mp_trusted_boot.c}}.<br> | ||
The {{Highlight|ROTPK}} is given in the high-level certificate and verified against a hash store OTP value: | The {{Highlight|ROTPK}} is given in the high-level certificate and verified against a hash store OTP value: | ||
Line 71: | Line 71: | ||
* On {{MicroprocessorDevice | device=13}}, multiple root keys are available on the platform which allow a key revocation mechanism. The multiple public key hashes are used to generate the final hash store in the {{Highlight|PKHTH}} section of [[STM32MP13_OTP_mapping|OTP]] which is controlled to confirm key integrity. The public key hash used is located in the Trusted Firmware-A BL2 [[STM32_header_for_binary_files#On_STM32MP13x_lines|STM32 header]] which is located in '''SRAM3'''. | * On {{MicroprocessorDevice | device=13}}, multiple root keys are available on the platform which allow a key revocation mechanism. The multiple public key hashes are used to generate the final hash store in the {{Highlight|PKHTH}} section of [[STM32MP13_OTP_mapping|OTP]] which is controlled to confirm key integrity. The public key hash used is located in the Trusted Firmware-A BL2 [[STM32_header_for_binary_files#On_STM32MP13x_lines|STM32 header]] which is located in '''SRAM3'''. | ||
{{ | |||
* On {{MicroprocessorDevice | device=25}}, multiple root keys are available on the platform which allow a key revocation mechanism. The multiple public key hashes are used to generate the final hash store in the {{Highlight|PKHTH}} section of [[STM32MP25_OTP_mapping|OTP]] which is controlled to confirm key integrity. The public key hash used is located in the Trusted Firmware-A BL2 [[STM32_header_for_binary_files#On_STM32MP25x_lines|STM32 header]] which is located in '''SYSRAM'''. | |||
{{Info|The default implementation uses the same public key as the [[STM32_MPU_ROM_code_overview|ROM Code]] to complete the SoC chain of trust.}} | |||
==== Define a custom RoT ==== | ==== Define a custom RoT ==== | ||
It is possible to change the ROTPK to have a dedicated public key for the CoT by changing the following: | It is possible to change the ROTPK to have a dedicated public key for the CoT by changing the following: | ||
* Use the | * Use the direct access to OTP value in {{CodeSource | TF-A | plat/st/common/stm32mp_trusted_boot.c}} | ||
* Define a new dedicated OTP value in the {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}} | * Define a new dedicated OTP value in the {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}} or {{CodeSource | TF-A | plat/st/stm32mp2/stm32mp2_def.h}} | ||
* Add a new entry in the board device tree in the fuse section with to defined name and OTP section. | * Add a new entry in the board device tree in the fuse section with to defined name and OTP section. | ||
* Get the value from the new defined OTP updating the {{CodeSource | TF-A | plat/st/common/stm32mp_trusted_boot.c}} | * Get the value from the new defined OTP updating the {{CodeSource | TF-A | plat/st/common/stm32mp_trusted_boot.c}} | ||
Line 94: | Line 97: | ||
* Non trusted non-volatile counter | * Non trusted non-volatile counter | ||
[[TAMP_internal_peripheral|TAMP]] monotonic counter is used to store the backup value, which requires backup battery to maintain the content. | |||
It is mandatory to align the same value between trusted and non-trusted value as only one counter is used as reference. This implies generating the certificate version number for each FIP image must match the common platform unique TAMP rollback counter. That is using the same argument value for options [[#STM32_MPU_build_options|--tfw-nvctr]] and [[#STM32_MPU_build_options|--ntfw-nvctr]] when generating the authenticated FIP image. | It is mandatory to align the same value between trusted and non-trusted value as only one counter is used as reference. This implies generating the certificate version number for each FIP image must match the common platform unique TAMP rollback counter. That is using the same argument value for options [[#STM32_MPU_build_options|--tfw-nvctr]] and [[#STM32_MPU_build_options|--ntfw-nvctr]] when generating the authenticated FIP image. | ||
=== STM32 firmware encryption === | === STM32 firmware encryption === | ||
On {{MicroprocessorDevice | device=13}}, it is possible to encrypt binary in the [[How_to_configure_TF-A_FIP|FIP]]. | On {{MicroprocessorDevice | device=13}} and {{MicroprocessorDevice | device=25}}, it is possible to encrypt binary in the [[How_to_configure_TF-A_FIP|FIP]]. | ||
The binary that can be encrypted must be defined in the {{CodeSource | TF-A | plat/st/common/stm32mp_fconf_io.c}}. | The binary that can be encrypted must be defined in the {{CodeSource | TF-A | plat/st/common/stm32mp_fconf_io.c}}. | ||
Line 105: | Line 108: | ||
Trusted Firmware-A provides a tool to manage {{DocSource | domain=TF-A | path=design/trusted-board-boot.html?authenticated-encryption-framework#authenticated-encryption-framework | text=the firmware encryption}}. | Trusted Firmware-A provides a tool to manage {{DocSource | domain=TF-A | path=design/trusted-board-boot.html?authenticated-encryption-framework#authenticated-encryption-framework | text=the firmware encryption}}. | ||
On {{MicroprocessorDevice | device=13}}, the current implementation uses the same key as the [[STM32_MPU_ROM_code_overview|ROM Code]] which is located in {{Highlight|EDMK}} section of [[STM32MP13_OTP_mapping|OTP]]. | |||
On {{MicroprocessorDevice | device=25}}, the current implementation uses a dedicated key which is located in {{Highlight|FIP-EDMK1}} section of [[STM32MP25_OTP_mapping|OTP]]. | |||
==== Define a custom encryption key ==== | ==== Define a custom encryption key ==== | ||
A new decryption key can be defined by updating: | A new decryption key can be defined by updating: | ||
* Redefine the <code>plat_get_enc_key_info</code> function to access the required OTP value in {{CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c}} | * Redefine the <code>plat_get_enc_key_info</code> function to access the required OTP value in {{CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c}} | ||
* Define a new dedicated OTP value in the {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}} | * Define a new dedicated OTP value (instead of ENCKEY_OTP) in the {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}} or {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp2_def.h}} | ||
* Add a new entry in the board device tree in the fuse section aligned with the defined name of OTP section. | * Add a new entry in the board device tree in the fuse section aligned with the defined name of OTP section. | ||
=== STM32 Cryptographic Library (CL) === | === STM32 Cryptographic Library (CL) === | ||
The | The STM32MPU platform supports '''ECDSA based certificate with SHA256''' signature.<br> | ||
A dedicated Cryptographic Library was implemented for STM32 MPU to use hardware accelerators {{CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c}}. | A dedicated Cryptographic Library was implemented for STM32 MPU to use hardware accelerators {{CodeSource | TF-A | plat/st/common/stm32mp_crypto_lib.c}}. | ||
It requires mbedTLS API to parse ASN1 certificate. | It requires mbedTLS API to parse ASN1 certificate. | ||
Line 122: | Line 127: | ||
** Verify a digital signature : ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses [[HASH_internal_peripheral|HASH]] and [[STM32_MPU_ROM_code_overview|ROM Code]] secure services. | ** Verify a digital signature : ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses [[HASH_internal_peripheral|HASH]] and [[STM32_MPU_ROM_code_overview|ROM Code]] secure services. | ||
** Verify a HASH : HASH calculation uses [[HASH_internal_peripheral|HASH]] | ** Verify a HASH : HASH calculation uses [[HASH_internal_peripheral|HASH]] | ||
* On {{MicroprocessorDevice | device=13}}: | * On {{MicroprocessorDevice | device=13}} and on {{MicroprocessorDevice | device=25}}: | ||
** ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses [[HASH_internal_peripheral|HASH]] and [[PKA_internal_peripheral|PKA]] hardware accelerators. | ** ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses [[HASH_internal_peripheral|HASH]] and [[PKA_internal_peripheral|PKA]] hardware accelerators. | ||
** Verify a HASH : HASH calculation uses [[HASH_internal_peripheral|HASH]] | ** Verify a HASH : HASH calculation uses [[HASH_internal_peripheral|HASH]] | ||
Line 135: | Line 140: | ||
It is possible to directly generate the [[How_to_configure_TF-A_FIP|FIP]] with all the necessary certificates using the specific build flag {{Highlight|GENERATE_COT{{=}}1}}. | It is possible to directly generate the [[How_to_configure_TF-A_FIP|FIP]] with all the necessary certificates using the specific build flag {{Highlight|GENERATE_COT{{=}}1}}. | ||
It is also possible to specify external keys. Otherwise, missing keys will be generated by the tool. | It is also possible to specify external keys. Otherwise, missing keys will be generated by the tool (certtool). | ||
{| class="st-table" | {| class="st-table" | ||
Line 162: | Line 167: | ||
{{Warning|The content of each certificate is different and because of the dependencies, it requires all long arguments list to regenerate a single certificate properly. By default, The FIP will manage to randomly generate the constructed certificates with the correct output.}} | {{Warning|The content of each certificate is different and because of the dependencies, it requires all long arguments list to regenerate a single certificate properly. By default, The FIP will manage to randomly generate the constructed certificates with the correct output.}} | ||
====Troubleshooting==== | |||
Since TF-A v2.8, the Openssl v3 is used to build '''certtool''' binary that generates the trusted boot chain certificates. By default, the OPENSSL_DIR uses the host openssl version. An additional flag can be set to redirect the openssl library path. | |||
When using the Yocto SDK, add the following path: | |||
<pre>OPENSSL_DIR=$OECORE_NATIVE_SYSROOT/bin</pre> | |||
== References == | == References == | ||
Line 169: | Line 179: | ||
{{PublicationRequestId | 24123 | 2022-07-27 | }} | {{PublicationRequestId | 24123 | 2022-07-27 | }} | ||
[[Category:Trusted_Firmware-A_(BL2)|02]] | [[Category:Trusted_Firmware-A_(BL2)|02]] | ||
[[Category: | [[Category:Secure boot]] | ||
</noinclude> | </noinclude> |
Latest revision as of 11:56, 6 June 2024
1. Article purpose
The main purpose of this article is to explain how the Trusted Board Boot feature support is managed in the Trusted Firmware-A component and the STM32 MPU specific implementation.
2. Overview
Trusted Firmware-A has a strong focus on security management.
It defines a reference implementation of secure software and implements the Trusted Board Boot requirements[1] specified by Arm®.
TF-A BL2 implements an authentication framework that uses a defined Chain of Trust (CoT) based on Arm® TBBR requirements to achieve a secure boot.
The authentication framework is enabled using a dedicated Trusted Firmware-A build flag in the BL2 command line:
TRUSTED_BOARD_BOOT=1
Some specific libraries are required to build tools and enable the TRUSTED_BOARD_BOOT : Prerequisites software library.
3. Chain of Trust (CoT)
To manage the Trusted Board Boot requirements, Trusted Firmware-A manages a public key Infrastructure (PKI) model so called Chain of Trust.
The Chain of Trust is following X509.v3[2] certificate standard adding some specific extensions and relies on a public key infrastructure (PKI) generating self-signed certificates. The Root of Trust of this chain is based on a Root of Trust Public Key (ROTPK).
Chain of Trust manages two certificate types:
- Key certificate used to verify public keys, which have been used to sign content certificates.
- Content certificate used to store the hash of a bootloader image.
Both certificates contain a non-volatile counter value that can be used for anti-rollback protection.
TF-A BL2 implements a default certificate chain to describe the PKI topology defined in fdts/cot_descriptors.dtsi . It is used by the firmware configuration framework to register into TF-A BL2 the chaining implementation based on generic CoT DTSI file. It describes the chain of trust following the specified bindings. STM32MPU platforms use a specific STM32MPU device tree which describes a specific topology for ST needs (see STM32 MPU implementation chapter). Based on this example, the PKI topology can be customized by customers.
Once generated, all the certificates are part of the FIP, which are updatable independently.
The certificate generation uses the default Trusted Firmware-A certificate creation tool.
4. Authentication framework
Trusted Firmware-A design an authentication framework to centralize all secure mechanism relying on an authentication module (AM), image parser module (IPM) and Crypto Module (CM). This generic framework based on the certificate chain of trust is responsible of the following:
- allocate memory for the loaded image
- identify the image and load it
- check the integrity
- authenticate / [ Decrypt ] the image
- extract the CoT information if needed to authenticate next image in CoT
A reference implementation has been integrated in Trusted Firmware-A using mbedTLS[3] for:
- the Image Parser Module(IPM) using x509.v3 certificate (Image Parser Library (IPL))
- the Crypto Module(CM) with a dedicated Cryptographic Library (CL).
5. STM32 MPU implementation
5.1. CoT
STM32 MPU is based on the standard Arm®TBBR PKI implementation. STM32MPU defines a specific fdts/stm32mp1-cot-descriptors.dtsi on STM32MP1 Series and fdts/stm32mp2-cot-descriptors.dtsi on STM32MP2 unknown microprocessor device in the TF-A BL2 device tree board file.
5.1.1. Define a custom CoT
It is possible to update the CoT by changing the chain of certificate. This must be done accordingly at:
- Certificate creation tool platform level plat/st/stm32mp1/stm32mp1_tbb_cert.c on STM32MP1 Series and plat/st/stm32mp2/stm32mp2_tbb_cert.c on STM32MP2 unknown microprocessor device.
- Custom device tree descriptor level fdts/stm32mp1-cot-descriptors.dtsi on STM32MP1 Series and fdts/stm32mp2-cot-descriptors.dtsi on STM32MP2 unknown microprocessor device following the bindings.
5.2. RoT
The Root of Trust Public Key (ROTPK) used as reference for the chain of trust.
The STM32 MPU platform plat_get_rotpk_info
implementation is made in : plat/st/common/stm32mp_trusted_boot.c .
The ROTPK is given in the high-level certificate and verified against a hash store OTP value:
- On STM32MP15x lines
, the hash of the public key used is located in the PKH section of OTP.
- On STM32MP13x lines
, multiple root keys are available on the platform which allow a key revocation mechanism. The multiple public key hashes are used to generate the final hash store in the PKHTH section of OTP which is controlled to confirm key integrity. The public key hash used is located in the Trusted Firmware-A BL2 STM32 header which is located in SRAM3.
- On STM32MP25 unknown microprocessor device, multiple root keys are available on the platform which allow a key revocation mechanism. The multiple public key hashes are used to generate the final hash store in the PKHTH section of OTP which is controlled to confirm key integrity. The public key hash used is located in the Trusted Firmware-A BL2 STM32 header which is located in SYSRAM.
![]() |
The default implementation uses the same public key as the ROM Code to complete the SoC chain of trust. |
5.2.1. Define a custom RoT
It is possible to change the ROTPK to have a dedicated public key for the CoT by changing the following:
- Use the direct access to OTP value in plat/st/common/stm32mp_trusted_boot.c
- Define a new dedicated OTP value in the plat/st/stm32mp1/stm32mp1_def.h or plat/st/stm32mp2/stm32mp2_def.h
- Add a new entry in the board device tree in the fuse section with to defined name and OTP section.
- Get the value from the new defined OTP updating the plat/st/common/stm32mp_trusted_boot.c
<New_OTP_define>, hash, len); }static int get_rotpk_hash(void *cookie, uint8_t *hash, size_t len) { if (cookie != NULL) { return -EINVAL; } return copy_hash_from_otp(
5.3. Non-volatile counters
Each certificate embeds a non-volatile counter value that is checked to control anti-rollback mechanism.
There are two non-volatile counters:
- Trusted non-volatile counter
- Non trusted non-volatile counter
TAMP monotonic counter is used to store the backup value, which requires backup battery to maintain the content.
It is mandatory to align the same value between trusted and non-trusted value as only one counter is used as reference. This implies generating the certificate version number for each FIP image must match the common platform unique TAMP rollback counter. That is using the same argument value for options --tfw-nvctr and --ntfw-nvctr when generating the authenticated FIP image.
5.4. STM32 firmware encryption
On STM32MP13x lines and STM32MP25 unknown microprocessor device, it is possible to encrypt binary in the FIP.
The binary that can be encrypted must be defined in the plat/st/common/stm32mp_fconf_io.c .
Trusted Firmware-A provides a tool to manage the firmware encryption.
On STM32MP13x lines , the current implementation uses the same key as the ROM Code which is located in EDMK section of OTP.
On STM32MP25 unknown microprocessor device, the current implementation uses a dedicated key which is located in FIP-EDMK1 section of OTP.
5.4.1. Define a custom encryption key
A new decryption key can be defined by updating:
- Redefine the
plat_get_enc_key_info
function to access the required OTP value in plat/st/common/stm32mp_crypto_lib.c - Define a new dedicated OTP value (instead of ENCKEY_OTP) in the plat/st/stm32mp1/stm32mp1_def.h or plat/st/stm32mp1/stm32mp2_def.h
- Add a new entry in the board device tree in the fuse section aligned with the defined name of OTP section.
5.5. STM32 Cryptographic Library (CL)
The STM32MPU platform supports ECDSA based certificate with SHA256 signature.
A dedicated Cryptographic Library was implemented for STM32 MPU to use hardware accelerators plat/st/common/stm32mp_crypto_lib.c .
It requires mbedTLS API to parse ASN1 certificate.
The Cryptographic Library (CL) defined the functions to:
5.6. STM32 MPU build options
To manage the Trusted Board Boot, TF-A_BL2 must be built using TRUSTED_BOARD_BOOT=1.
When TRUSTED_BOARD_BOOT=1 has been set, the FIP must embed all the certificates.
It is possible to directly generate the FIP with all the necessary certificates using the specific build flag GENERATE_COT=1.
It is also possible to specify external keys. Otherwise, missing keys will be generated by the tool (certtool).
Description | Makefile Flag | certificate creation tool args |
---|---|---|
Root public key | ROT_KEY | --rot-key |
Algorithm used for key generation | KEY_ALG | --key-alg |
Algorithm used for hash | HASH_ALG | --hash-alg |
Trusted word key | TRUSTED_WORLD_KEY | --trusted-world-key |
Non Trusted word key | NON_TRUSTED_WORLD_KEY | --non-trusted-world-key |
Trusted Firmware Non volatile counter | TFW_NVCTR_VAL | --tfw-nvctr |
Non Trusted Firmware Non volatile counter | NTFW_NVCTR_VAL | --ntfw-nvctr |
Trusted key certificate | TRUSTED_KEY_CERT | --trusted-key-cert |
STM32MP configuration certificate | STM32MP_CFG_CERT | --stm32mp-cfg-cert |
5.6.1. Troubleshooting
Since TF-A v2.8, the Openssl v3 is used to build certtool binary that generates the trusted boot chain certificates. By default, the OPENSSL_DIR uses the host openssl version. An additional flag can be set to redirect the openssl library path. When using the Yocto SDK, add the following path:
OPENSSL_DIR=$OECORE_NATIVE_SYSROOT/bin6. References