Difference between revisions of "TF-A BL2 Trusted Board Boot"

[quality revision] [quality revision]
m
m
 
Applicable for STM32MP13x lines, STM32MP15x lines

1 Article purpose[edit]

The main purpose of this article is to explain how the the Trusted Board Boot feature support is managed in the Trusted Firmware-A component and the STM32 MPU specific implementation.

2 Overview[edit]

Trusted Firmware-A as 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.

Warning white.png Warning
The TRUSTED_BOARD_BOOT=1 is mandatory as soon as the MPU is in Secure Close state.

3 Chain of Trust (CoT)[edit]

To manage the Trusted Board Boot requirements, Trusted Firmware-A manages a Public Key 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 2 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 boot loader 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. It uses the firmware configuration framework to register into TF-A BL2 the chaining implementation based on default STM32MP device tree include fdts/cot_descriptors.dtsi . It describes the chain of trust following the specified bindings.

Once generated, all the certificates will be are part of the FIP, which will be are updatable independently.

The certificate generation uses the default Trusted Firmware-A certificate creation tool.

4 Authentication Frameworkframework[edit]

Trusted Firmware-A design an authentication framework to centralize all secure mecanism mechanism relying on Authentication Modulean authentication module (AM), Image Parser Module image parser module (IPM) and Crypto Module (CM). This generic framework based on the certificate chain of trust is responsible of the following:

  • Allocating allocate memory for the loaded image
  • Identify identify the image and load it
  • Check check the integrity
  • Authenticate authenticate / [ Decrypt ] the image
  • Extract 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[edit]

5.1 CoT[edit]

STM32 MPU uses is based on the standard Arm®TBBR PKI implementation by including the generic . STM32MPU defines a specific fdts/stm32mp1-cot_-descriptors.dtsi in the TF-A BL2 device tree board file.

Warning white.png Warning
This CoT description is defined in the BL2 device tree so it cannot be changed without any TF-A BL2 update

5.1.1 Define a custom CoT[edit]

It is possible to update the CoT by changing the chain of certificate. This must be done accordingly at:

5.2 RoT[edit]

The Root of Trust Public Key (ROTPK) used as reference for the chain of trust.
The STM32MP1 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 More info.png, the hash of the public key used is located in the PKH section of OTP.
  • On STM32MP13x lines Warning.png, 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.
Warning white.png Warning
The default implementation uses the same public key as the ROM Code.

5.2.1 Define a custom RoT[edit]

It is possible to change the ROTPK to have a dedicated public key for the CoT by changing the following:

 static int get_rotpk_hash(void *cookie, uint8_t *hash, size_t len)
 {
   if (cookie != NULL) {
      return -EINVAL;
   }
   return copy_hash_from_otp(<New_OTP_define>, hash, len);
 }

5.3 Non-volatile counters[edit]

Each certificate embeds a non-volatile counter value that is checked to control anti-rollback mechanism.
There are 2 two non-volatile counters: - Trusted Non non-volatile counter - Non trusted volatile counter

On STM32MP1, 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.

5.4 STM32 FW Encryptionfirmware encryption[edit]

On STM32MP13x lines Warning.png, 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.

The current implementation uses the same key as the ROM Code which is located in EDMK section of OTP.

5.4.1 Define a custom Encryption Keyencryption key[edit]

A new decryption key can be defined by updating:

5.5 STM32 Crypto Cryptographic Library (CL)[edit]

The STM32MP1 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:

  • On STM32MP15x lines More info.png:
    • Verify a digital signature : ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses HASH and ROM Code secure services.
    • Verify a HASH : HASH calculation uses HASH
  • On STM32MP13x lines Warning.png:
    • ECDSA based authentication (P256NIST or BRAINPOOL_P256T1) uses HASH and PKA hardware accelerators.
    • Verify a HASH : HASH calculation uses HASH
    • Decrypt and verify a binary using SAES (Limited to AES GCM mode)

5.6 STM32 MPU build options[edit]

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.

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


Warning white.png 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.

6 References[edit]



<noinclude>{{ApplicableFor
|MPUs list=STM32MP13x, STM32MP15x
|MPUs checklist=STM32MP13x,STM32MP15x
}}</noinclude>

==Article purpose==
The main purpose of this article is to explain how the the Trusted Board Boot feature support is managed in the Trusted Firmware-A component and the STM32 MPU specific implementation.

==Overview==
Trusted Firmware-A ashas a strong focus on security management.
It defines a reference implementation of secure software and implements the Trusted Board Boot requirements<ref>https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a</ref> specified by Arm<sup>&reg;</sup>.
TF-A BL2 implements an authentication framework that uses a defined Chain of Trust (CoT) based on Arm<sup>&reg;</sup> TBBR requirements to achieve a secure boot.<br>


The authentication framework is enabled using a dedicated [[How_to_configure_TF-A_BL2#Build_command_details|Trusted Firmware-A build flag]] in the BL2 command line: <br> 

{{Highlight|'''TRUSTED_BOARD_BOOT{{=}}1'''}}

Some specific libraries are required to build tools and enable the {{Highlight|'''TRUSTED_BOARD_BOOT'''}} : {{DocSource | domain=TF-A | path=getting_started/prerequisites.html#software-and-libraries | text= Prerequisites software library}}.

{{Warning | The {{Highlight|'''TRUSTED_BOARD_BOOT{{=}}1'''}} is mandatory as soon as the MPU is in Secure Close state. }}

== Chain of Trust (CoT)==
To manage the Trusted Board Boot requirements, Trusted Firmware-A manages a Public Keypublic key Infrastructure (PKI) model so called {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#chain-of-trust | text=Chain of Trust }}.

The Chain of Trust is following X509.v3<ref>https://tools.ietf.org/rfc/rfc5280.txt</ref> 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 2two 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 boot loader 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. It uses the {{DocSource | domain=TF-A | path=components/fconf/index.html | text=firmware configuration framework}} to register into TF-A BL2 the chaining implementation based ondefaultSTM32MP device tree include {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}}. It describes the chain of trust following the specified {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.

Once generated, all the certificates will be are part of the [[How_to_configure_TF-A_FIP|FIP]], which will be are updatable independently.

The certificate generation uses the default Trusted Firmware-A {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#certificate-generation-tool | text=certificate creation tool}}.

== Authentication Frameworkframework ==
Trusted Firmware-A design an {{DocSource | domain=TF-A | path=design/auth-framework.html | text=authentication framework}} to centralize all secure mecanismmechanism relying on Authentication Module(AM), Image Parser Modulean authentication module (AM), image parser module (IPM) and Crypto Module (CM).
This generic framework based on the certificate chain of trust is responsible of:
* Allocating memory for loaded image
* Identify the following:
* allocate memory for the loaded image
* identify the image and load it
* Checkcheck the integrity
* Authenticateauthenticate / [ Decrypt ] the image
* Extractextract the CoT information if needed to authenticate next image in CoT.


A reference implementation has been integrated in Trusted Firmware-A using mbedTLS<ref>https://www.trustedfirmware.org/projects/mbed-tls/</ref> for:
* the Image Parser Module(IPM) using x509.v3 certificate (Image Parser Library (IPL))
* the Crypto Module(CM) with a dedicated Cryptographic Library (CL).

== STM32 MPU implementation==
=== CoT ===
STM32 MPU uses is based on the standard Arm<sup>&reg;</sup>TBBR PKI implementation by including the generic. STM32MPU defines a specific {{CodeSource | TF-A | fdts/stm32mp1-cot_-descriptors.dtsi}}  in the TF-A BL2 device tree board file.
<div class="res-img">

[[File:certificate_chain_with_leg.png|center|Caption]]</div>

{{Warning|This CoT description is defined in the BL2 device tree so '''it cannot be changed without any TF-A BL2 update'''}}

==== 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 {{CodeSource | TF-A | tools/cert_create/src/tbbr/plat/st/stm32mp1/stm32mp1_tbb_cert.c }}.
* Device tree board}}.
* Custom device tree descriptor level {{CodeSource | TF-A | fdts/ }} including a custom device tree descriptor stm32mp1-cot-descriptors.dtsi}}  following the {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.

=== RoT ===
The Root of Trust Public Key ({{Highlight|ROTPK}}) used as reference for the chain of trust.<br>

The STM32MP1 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:
* On {{MicroprocessorDevice | device=15}}, the hash of the public key used is located in the {{Highlight|PKH}} section of [[STM32MP15_OTP_mapping|OTP]].<br>


* 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'''.
{{Warning|The default implementation uses the same public key as the [[STM32_MPU_ROM_code_overview|ROM Code]].}}

==== 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 {{MicroprocessorDevice | device=15}} 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}}
* 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}}

  static int get_rotpk_hash(void *cookie, uint8_t *hash, size_t len)
  {
    if (cookie != NULL) {
       return -EINVAL;
    }
    return copy_hash_from_otp({{Highlight|<New_OTP_define>}}, hash, len);
  }

=== Non -volatile counters ===
Each certificate embeds a non -volatile counter value that is checked to control anti-rollback mechanism.<br>

There are 2two non -volatile counters:
- Trusted Non non-volatile counter
- Non trusted volatile counter

On STM32MP1, [[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.

=== STM32 FW Encryptionfirmware encryption ===
On {{MicroprocessorDevice | device=13}}, 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}}.

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}}.

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]].

==== Define a custom Encryption Keyencryption key ====
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}}
* Define a new dedicated OTP value in the {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_def.h}}
* Add a new entry in the board device tree in the fuse section aligned with the defined name of OTP section.

=== STM32 CryptoCryptographic Library (CL) ===
The STM32MP1 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}}.
It requires mbedTLS API to parse ASN1 certificate.

The Cryptographic Library (CL) defined the functions to:
* On {{MicroprocessorDevice | device=15}}: 
** 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]]
* On {{MicroprocessorDevice | device=13}}:
** 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]]
** Decrypt and verify a binary using [[SAES_internal_peripheral|SAES]] (Limited to AES GCM mode)

=== STM32 MPU build options ===

To manage the Trusted Board Boot, [[How_to_configure_TF-A_BL2#Secure_boot_support|TF-A_BL2]] must be built using {{Highlight|'''TRUSTED_BOARD_BOOT{{=}}1'''}}.

When {{Highlight|'''TRUSTED_BOARD_BOOT{{=}}1'''}} has been set, the [[How_to_configure_TF-A_FIP|FIP]] must embed all the certificates.

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.

{| class="st-table"
|-
! Description  !! Makefile Flag !! {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#certificate-generation-tool | text=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
|}

{{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.}}

== References ==<references />

<noinclude>
{{PublicationRequestId | 24123 | 2022-07-27 | }}[[Category:Trusted_Firmware-A_(BL2)|02]]
[[Category:Platform Securitysecurity]]</noinclude>
(12 intermediate revisions by 5 users not shown)
Line 4: Line 4:
 
}}</noinclude>
 
}}</noinclude>
 
==Article purpose==
 
==Article purpose==
The main purpose of this article is to explain how the the Trusted Board Boot support is managed in the Trusted Firmware-A component and the STM32 MPU specific implementation.
+
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.
   
 
==Overview==
 
==Overview==
Trusted Firmware-A as a strong focus on security management.
+
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<ref>https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a</ref> specified by Arm<sup>&reg;</sup>.
 
It defines a reference implementation of secure software and implements the Trusted Board Boot requirements<ref>https://developer.arm.com/docs/den0006/latest/trusted-board-boot-requirements-client-tbbr-client-armv8-a</ref> specified by Arm<sup>&reg;</sup>.
 
TF-A BL2 implements an authentication framework that uses a defined Chain of Trust (CoT) based on Arm<sup>&reg;</sup> TBBR requirements to achieve a secure boot.<br>
 
TF-A BL2 implements an authentication framework that uses a defined Chain of Trust (CoT) based on Arm<sup>&reg;</sup> TBBR requirements to achieve a secure boot.<br>
 
   
 
The authentication framework is enabled using a dedicated [[How_to_configure_TF-A_BL2#Build_command_details|Trusted Firmware-A build flag]] in the BL2 command line: <br>  
 
The authentication framework is enabled using a dedicated [[How_to_configure_TF-A_BL2#Build_command_details|Trusted Firmware-A build flag]] in the BL2 command line: <br>  
Line 20: Line 19:
   
 
== Chain of Trust (CoT)==
 
== Chain of Trust (CoT)==
To manage the Trusted Board Boot requirements, Trusted Firmware-A manages a Public Key Infrastructure (PKI) model so called {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#chain-of-trust | text=Chain of Trust }}.
+
To manage the Trusted Board Boot requirements, Trusted Firmware-A manages a public key Infrastructure (PKI) model so called {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#chain-of-trust | text=Chain of Trust }}.
   
 
The Chain of Trust is following X509.v3<ref>https://tools.ietf.org/rfc/rfc5280.txt</ref> certificate standard adding some specific extensions and relies on a public key infrastructure (PKI) generating self-signed certificates.
 
The Chain of Trust is following X509.v3<ref>https://tools.ietf.org/rfc/rfc5280.txt</ref> 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).
 
The Root of Trust of this chain is based on a Root of Trust Public Key (ROTPK).
   
Chain of Trust manages 2 certificate types:
+
Chain of Trust manages two certificate types:
* '''Key certificate''' used to verify public keys which have been used to sign content certificates.
+
* '''Key certificate''' used to verify public keys, which have been used to sign content certificates.
* '''Content certificate''' used to store the hash of a boot loader image.
+
* '''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.
+
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. It uses 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
 
TF-A BL2 implements a default certificate chain to describe the PKI topology. It uses 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
default device tree include {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}}. It describes the chain of trust following the specified {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.
+
STM32MP device tree include {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}}. It describes the chain of trust following the specified {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.
   
Once generated, all the certificates will be part of the [[How_to_configure_TF-A_FIP|FIP]] which will be updatable independently.
+
Once generated, all the certificates are part of the [[How_to_configure_TF-A_FIP|FIP]], which are updatable independently.
   
 
The certificate generation uses the default Trusted Firmware-A {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#certificate-generation-tool | text=certificate creation tool}}.
 
The certificate generation uses the default Trusted Firmware-A {{DocSource | domain=TF-A | path=design/trusted-board-boot.html#certificate-generation-tool | text=certificate creation tool}}.
   
== Authentication Framework ==
+
== Authentication framework ==
Trusted Firmware-A design an {{DocSource | domain=TF-A | path=design/auth-framework.html | text=authentication framework}} to centralize all secure mecanism relying on Authentication Module(AM), Image Parser Module (IPM) and Crypto Module (CM).
+
Trusted Firmware-A design an {{DocSource | domain=TF-A | path=design/auth-framework.html | text=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 certificate chain of trust is responsible of:
+
This generic framework based on the certificate chain of trust is responsible of the following:
* Allocating memory for loaded image
+
* allocate memory for the loaded image
* Identify the image and load it
+
* identify the image and load it
* Check the integrity
+
* check the integrity
* Authenticate / [ Decrypt ] the image
+
* authenticate / [ Decrypt ] the image
* Extract the CoT information if needed to authenticate next image in CoT.
+
* extract the CoT information if needed to authenticate next image in CoT
   
 
A reference implementation has been integrated in Trusted Firmware-A using mbedTLS<ref>https://www.trustedfirmware.org/projects/mbed-tls/</ref> for:
 
A reference implementation has been integrated in Trusted Firmware-A using mbedTLS<ref>https://www.trustedfirmware.org/projects/mbed-tls/</ref> for:
Line 53: Line 52:
 
== STM32 MPU implementation==
 
== STM32 MPU implementation==
 
=== CoT ===
 
=== CoT ===
STM32 MPU uses the standard Arm<sup>&reg;</sup>TBBR PKI implementation by including the generic {{CodeSource | TF-A | fdts/cot_descriptors.dtsi}} in the TF-A BL2 device tree board file.
+
STM32 MPU is based on the standard Arm<sup>&reg;</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.
   
 
<div class="res-img">
 
<div class="res-img">
Line 62: Line 61:
 
==== 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 level {{CodeSource | TF-A | tools/cert_create/src/tbbr/tbb_cert.c }}.
+
* Certificate creation tool platform level {{CodeSource | TF-A | plat/st/stm32mp1/stm32mp1_tbb_cert.c}}.
* Device tree board level {{CodeSource | TF-A | fdts/ }} including a custom device tree descriptor following the {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.
+
* Custom device tree descriptor level {{CodeSource | TF-A | fdts/stm32mp1-cot-descriptors.dtsi}} following the {{DocSource | domain=TF-A | path=components/cot-binding.html | text=bindings}}.
   
 
=== RoT ===
 
=== RoT ===
Line 69: Line 68:
 
The STM32MP1 platform <code>plat_get_rotpk_info</code> implementation is made in : {{CodeSource | TF-A | plat/st/common/stm32mp_trusted_boot.c}}.<br>
 
The STM32MP1 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:
 
* On {{MicroprocessorDevice | device=15}}, the hash of the public key used is located in the {{Highlight|PKH}} section of [[STM32MP15_OTP_mapping|OTP]].<br>
 
* On {{MicroprocessorDevice | device=15}}, the hash of the public key used is located in the {{Highlight|PKH}} section of [[STM32MP15_OTP_mapping|OTP]].<br>
   
Line 90: Line 89:
 
   }
 
   }
   
=== Non volatile counters ===
+
=== Non-volatile counters ===
Each certificate embeds a non volatile counter value that is checked to control anti-rollback mechanism.<br>
+
Each certificate embeds a non-volatile counter value that is checked to control anti-rollback mechanism.<br>
There are 2 non volatile counters:
+
There are two non-volatile counters:
- Trusted Non volatile counter
+
- Trusted non-volatile counter
 
- Non trusted volatile counter
 
- Non trusted volatile counter
   
On STM32MP1, [[TAMP_internal_peripheral|TAMP]] monotonic counter is used to store the backup value which requires backup battery to maintain the content.
+
On STM32MP1, [[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.
+
It is mandatory to align the same value between trusted and non-trusted value as only one counter is used as reference.
   
=== STM32 FW 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}}, it is possible to encrypt binary in the [[How_to_configure_TF-A_FIP|FIP]].
   
Line 108: Line 107:
 
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]].
 
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]].
   
==== 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}}
Line 114: Line 113:
 
* 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 Crypto Library (CL) ===
+
=== STM32 Cryptographic Library (CL) ===
 
The STM32MP1 platform supports '''ECDSA based certificate with SHA256''' signature.<br>
 
The STM32MP1 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}}.
Line 157: Line 156:
 
|-
 
|-
 
| Trusted key certificate || TRUSTED_KEY_CERT || --trusted-key-cert
 
| Trusted key certificate || TRUSTED_KEY_CERT || --trusted-key-cert
  +
|-
  +
| STM32MP configuration certificate || STM32MP_CFG_CERT || --stm32mp-cfg-cert
 
|}
 
|}
   
Line 166: Line 167:
   
 
<noinclude>
 
<noinclude>
  +
{{PublicationRequestId | 24123 | 2022-07-27 | }}
 
[[Category:Trusted_Firmware-A_(BL2)|02]]
 
[[Category:Trusted_Firmware-A_(BL2)|02]]
[[Category:Platform Security]]
+
[[Category:Platform security]]
 
</noinclude>
 
</noinclude>