From 099600ce0fa870303627328a525ce089223f92e7 Mon Sep 17 00:00:00 2001 From: Katrina Prosise Date: Thu, 1 Feb 2024 06:07:04 -0500 Subject: [PATCH] Cleanup edge-lock-se05x page Edited to improve readability and to follow style guide. QA Steps: Ran linter and spellcheck in editor. Viewed rendered output. This commit applies to FFTK 2795 Signed-off-by: Katrina Prosise --- .../secure-elements/secure-element.050.rst | 224 ++++++++---------- 1 file changed, 97 insertions(+), 127 deletions(-) diff --git a/source/reference-manual/security/secure-elements/secure-element.050.rst b/source/reference-manual/security/secure-elements/secure-element.050.rst index 1fba53ee9..43c6ea2b7 100644 --- a/source/reference-manual/security/secure-elements/secure-element.050.rst +++ b/source/reference-manual/security/secure-elements/secure-element.050.rst @@ -5,8 +5,9 @@ EdgeLock™ SE05x: Plug & Trust Secure Element ============================================ -There is extensive documentation online about the EdgeLock™ SE05x Secure Element -so we won't duplicate it here; however for reference we recommend the following reads: +There is extensive documentation online about the EdgeLock™ SE05x Secure Element. +It will not be duplicated here. +However, for reference we recommend the following: **Data Sheet**: `SE05x Plug & Trust Secure Element`_ @@ -19,96 +20,81 @@ so we won't duplicate it here; however for reference we recommend the following **User Manuals**: `NXP SE05x T=1 Over I2C Specification`_ -The EdgeLock™ SE05x follows the Global Platform Card Specification. So on top of -the previously suggested product documentation we also advise to get some awareness -of the specification by reading the following documents: +The EdgeLock™ SE05x follows the Global Platform Card Specification. +In addition to the product documentation above, we advise awareness of the specification by reading the following documents: **Global Platform Specifications**: `Card Specification 2.3.1`_, `Secure Channel Protocol 03`_ NXP SE05x Plug & Trust MW -------------------------- -NXP provides a software stack, the SE05x Plug&Trust Middleware, to support this -device in a number of environments. + +NXP® provides a software stack, the SE05x Plug&Trust Middleware, to support this device in a number of environments. There is also extensive documentation in the form of PDF and HTML browsable documents within the freely downloadable `NXP SE05x Plug & Trust MW`_ software package. -We recommend users to download and succinctly read them to better understand what -the product has to offer. +We recommend downloading and reading them indepth to better understand what the product has to offer. + +A reduced open source version of this middleware is the Plug-and-Trust `mini package`_ used in our OP-TEE integration. +We forked the repository and maintain it on our public GitHub server. -A reduced open source version of this middleware is the Plug-and-Trust `mini -package`_ used in our OP-TEE integration. We forked the repository and -maintain it on our public github server. Since support for the SE05x -exists in OP-TEE upstream, OP-TEE references this project in order to run its -Azure CI pipeline and avoid build regressions. +Support for the SE05x exists in OP-TEE upstream. +OP-TEE references this project in order to run its Azure CI pipeline and avoid build regressions. .. note:: - The support for the SE05x in OP-TEE is generic and not platform dependent: it - only requires an OP-TEE native I2C driver to enable SCP03 early during boot. + The support for the SE05x in OP-TEE is generic and not platform dependent. + It only requires an OP-TEE native I2C driver to enable SCP03 early during boot. NXP SE05x Plug & Trust TEE Integration -------------------------------------- -At Foundries.io we believe in securing systems by extending the perimeter of the -**hardware root of trust** to as many operational phases as possible: secure monitoring, -secure authentication, storage protection, secure communication and key management. +At Foundries.io, we believe in securing systems by extending the perimeter of the **hardware root of trust** to as many operational phases as possible: +secure monitoring, secure authentication, storage protection, and secure communication and key management. -Because a number of our customers have been targeting the NXP SE05x in their designs, -we chose to integrate the NXP middleware with our ROT (root of trust) by bringing -it under the umbrella of our Trusted Execution Environment: OP-TEE. +For those targeting the NXP SE05x in their designs, we chose to integrate the NXP middleware with our ROT (root of trust). +We did this by bringing it under the umbrella of our Trusted Execution Environment: OP-TEE. -The SE05x middleware is a behemoth of a software stack: highly configurable, highly -flexible and therefore sometimes difficult to navigate. And derived from its flexibility -comes its complexity and size - well over half a million lines of code. +The SE05x middleware is a behemoth of a software stack: highly configurable, highly flexible and therefore sometimes difficult to navigate. +From its flexibility comes complexity and size—well over half a million lines of code. -Fortunately, most of the functionality provided by the TEE overlaps with that -provided by the SE05x; in particular all cryptographic operations have a software -mirror implementation in OP-TEE: ECC, RSA, MAC, HASH, AES, 3DES and so forth. +Fortunately, most of the functionality provided by the TEE overlaps with that provided by the SE05x. +In particular, all cryptographic operations have a software mirror implementation in OP-TEE: ECC, RSA, MAC, HASH, AES, 3DES and so forth. -This meant that we could validate our integration using the OP-TEE crypto regression -test suite from the `OP-TEE tests`_ +This meant that we could validate our integration using the OP-TEE crypto regression test suite from the `OP-TEE tests`_ The main advantage of using the SE05x in a product design which already runs a TEE -is that all private keys programmed in the device's non volatile memory will never -be leaked to the outside world. +is that all private keys programmed in the device's non volatile memory will never be leaked to the outside world. -The SE05x also provides a real random number generator which can be exported to -the REE (normal world) to improve its entropy requirements. +The SE05x also provides a real random number generator which can be exported to the REE (normal world) to improve its entropy requirements. -Because the TEE is its only client, the TEE SE05x stack only requires a single -global session and key store. Policies are configured so only the SCP03 enabled -session can access its objects for creation or deletion. +Because the TEE is its only client, the TEE SE05x stack only requires a single global session and key store. +Policies are configured so only the SCP03 enabled session can access its objects for creation or deletion. OP-TEE Integration ------------------- -The SE05x standard physical interface is I2C typically configured as a target running -in high speed mode (3.4Mbps). Since the SE05x could replace the OP-TEE default crypto -operations (software), we chose to implement a native I2C driver so the SE05x -could be accessed as early as possible. +The SE05x standard physical interface is I2C typically configured as a target running in high speed mode (3.4Mbps). +Since the SE05x could replace the OP-TEE default crypto operations (software), we chose to implement a native I2C driver. +This is so the SE05x could be accessed as early as possible. -OP-TEE's cryptographic providers are not runtime configurable meaning that the user -must choose at compile time where to execute its cryptographic functions: whether in -libmbedtls, libtomcrypt or now in the SE05x. But this is **not** an all or nothing configuration -and operations can be routed to one service or another; for instance on an iMX platform -the Hardware Unique Key could be retrieved from the CAAM, AES ECB and HASH operations implemented -in libtomcrypt, and RNG, ECC and RSA in the SE05x. +OP-TEE's cryptographic providers are not runtime configurable. +This means the user must choose at compile time where to execute its cryptographic functions: +whether in libmbedtls, libtomcrypt or now in the SE05x. +But this is **not** an all or nothing configuration, and operations can be routed to one service or another. +For instance, on an iMX platform the Hardware Unique Key (HUK) could be retrieved from the CAAM, AES ECB, +and HASH operations implemented in libtomcrypt, and also RNG, ECC, and RSA in the SE05x. .. note:: - As a typical scenario, choosing to run AES ECB and HASH on the SE05x might - be a bad idea due to its performance implications as those operations are heavily - used to verify the trusted filesystem in OP-TEE and would dramatically slow down - the opening of trusted applications. + In a typical scenario, choosing to run AES ECB and HASH on the SE05x might be a bad idea due to its performance implications. + Those operations are heavily used to verify the trusted filesystem in OP-TEE, and would dramatically slow down the opening of trusted applications. Serial Communications to the SE05x ---------------------------------- -The first step taken during the integration work was to develop and upstream a -native I2C driver (imx_i2c). But since this driver could not be used once the REE -started executing - as it would not protect against I2C bus collisions or power management -implementations controlled from the REE - we needed a second driver: a sort of i2c -trampoline service capable to routing I2C read and write operations from OP-TEE to -the REE driver (Linux in particular). +The first step taken during integration work was to develop and upstream a native I2C driver (imx_i2c). +But since this driver could not be used once the REE started executing—as it would not protect against I2C bus collisions or power management +implementations controlled from the REE—we needed a second driver. +This would serve as a i2c trampoline service, capable of routing I2C read and write operations from OP-TEE to the REE driver (Linux® in particular). .. note:: These drivers are configurable using the following build options:: @@ -119,91 +105,80 @@ the REE driver (Linux in particular). Secure Communication Protocol 03 --------------------------------- -The SE05x has native support for Global Platform Secure Communication Protocol 03 which -allows us to protect the integrity of end to end communications between the -processor and the SE05x. All data sent to the SE05x is software encrypted and all -data received is then decrypted in the TEE using a set of session specific keys. +The SE05x has native support for Global Platform Secure Communication Protocol 03. +This allows us to protect the integrity of end-to-end communications between the processor and the SE05x. +All data sent to the SE05x is software encrypted. +All data received is decrypted in the TEE, using a set of session specific keys. These keys are derived from predefined keys which are shipped with the devices. .. note:: - The user can select whether to enable SCP03 during the secure world initialization - or at a later time from the normal world by using the `scp03`_ command:: + You can select whether to enable SCP03 during the secure world initialization, + or at a later time, using the `scp03`_ command:: CFG_CORE_SE05X_SCP03_EARLY=y : enables SCP03 before the Normal World has booted CFG_SCP03_PTA=y : allows SCP03 to be enabled from the Normal World. -The predefined factory keys stored on the SE05X NVM (**static keys** from here -on) are public and should therefore be rotated to a secret set from -which session keys can be derived. +The predefined factory keys stored on the SE05X NVM (**static keys** from here on) are public. +Therefore, they should be rotated to a secret set from which session keys can be derived. -To avoid having to store new static keys — reducing the surface attack and -simplifying the firmware upgrade process — the new set of keys will be derived in -OP-TEE from its core secret: the Hardware Unique Key (HUK) +Avoiding the need to store new static keys reduces attack surface and simplifies the firmware upgrade process. +To this end, the new set of keys will be derived in OP-TEE from its core secret: the Hardware Unique Key (HUK) .. warning:: - Once the static SCP03 keys have been derived from the HUK and programmed - into the device's NVM the **HUK MUST NOT CHANGE**. - + Once the static SCP03 keys have been derived from the HUK and programmed into the device's NVM, the **HUK MUST NOT CHANGE**. It is equally critical that the HUK remains a **secret**. -There are two different ways of rotating the SCP03 key: with and without user -intervention from the Normal World. +There are two different ways of rotating the SCP03 key: with and without user intervention from the Normal World. -To rotate the static SCP03 keys from the Trust Zone before the Normal World is -executing, the user should enable **CFG_CORE_SE05X_SCP03_PROVISION_ON_INIT=y**. +To rotate the static SCP03 keys from the Trust Zone before the Normal World is executed, +enable ``CFG_CORE_SE05X_SCP03_PROVISION_ON_INIT=y``. -To rotate the static SCP03 keys from the Normal World, the user should enable -**CFG_CORE_SE05X_SCP03_PROVISION=y** and then use the `scp03`_ command. +To rotate the static SCP03 keys from the Normal World, +enable ``CFG_CORE_SE05X_SCP03_PROVISION=y`` and then use the `scp03`_ command. SE05x Non Volatile Memory ------------------------- -The current implementation of the SE05x TEE driver only allows for permanent -storage of the ECC and RSA keys. These keys can be managed using the cryptoki -API implementing the pkcs#11 standard. External keys used by the SE05x to perform -other cryptographic operations are not stored in the SE05x NVM. +The current implementation of the SE05x TEE driver only allows for permanent storage of the ECC and RSA keys. +These keys can be managed using the cryptoki API implementing the pkcs#11 standard. +External keys used by the SE05x to perform other cryptographic operations are not stored in the SE05x NVM. .. note:: The SE05x NVM can be cleared by setting the following configuration option:: - CFG_CORE_SE05X_INIT_NVM=y + CFG_CORE_SE05X_INIT_NVM=y - Alternatively, the SE05x NVM can also be cleared by issuing the following - command on the target: :: + Alternatively, the SE05x NVM can also be cleared by issuing the following command on the target:: - $ ssscli se05x reset + $ ssscli se05x reset - The ssscli tool will be discussed in the next section. + The ssscli tool will be discussed in the next section. -Be aware that initializing the NVM would cause all keys and objects to be deleted -from permanent storage, but would not affect any handles that the PKCS#11 TA -might have stored in its database which would now point nowhere. -This configuration option however has no impact on the SCP03 set of static keys -which will remain unchanged. +Be aware that initializing the NVM would cause all keys and objects to be deleted from permanent storage. +This would not affect any handles that the PKCS#11 TA might have stored in its database, which would now point nowhere. +However, this configuration option has no impact on the SCP03 set of static keys which will remain unchanged. -Importing Secure Objects to PKCS#11 tokens +Importing Secure Objects to PKCS#11 Tokens ------------------------------------------ -After manufacturing, the NXP SE05x will contain pre-provisioned keys and -certificates. These secure objects will be known to the user through their -product specific internal documentation and will be accessible from the TEE by -their 32 bit identifiers. +After manufacturing, the NXP SE05x will contain pre-provisioned keys and certificates. +These secure objects can be known through their product specific internal documentation. +They will also be accessible from the TEE by their 32 bit identifiers. -To import those objects into PKCS#11 tokens, we have extended the `TEE pkcs#11 -implementation`_. This allows the user to call standard tools like pkcs11-tool -to import keys into the database; as we said earlier, private keys can't be -exposed outside the secure element and therefore these calls shall only import -the handles to access those keys. The SE05x OP-TEE driver is prepared to work -with either keys or key handles. Storing handles in the pkcs#11 -database does not impose restrictions to the user. +To import those objects into PKCS#11 tokens, we have extended the `TEE pkcs#11 implementation`_. +This allows the user to call standard tools like pkcs11-tool to import keys into the database. +As previously noted, private keys can not be exposed outside the secure element. +Therefore, these calls only import the handles to access those keys. +The SE05x OP-TEE driver is prepared to work with either keys or key handles. +Storing handles in the pkcs#11 database does not impose restrictions. .. note:: - The private key will be a handle to the actual key in the element NVM: - private keys are **never** exposed outside the NXP SE05x. For example, to - import the data-sheet documented 32 bit 0xF7000001 RSA 4096 bit key into - the pkcs#11 database, issue the following command: + The private key will be a handle to the actual key in the element NVM. + Private keys are **never** exposed outside the NXP SE05x. + For example, to import the data-sheet documented 32 bit 0xF7000001 RSA 4096 bit key into the pkcs#11 database, + issue the following command: .. code-block:: none @@ -211,27 +186,23 @@ database does not impose restrictions to the user. We have also developed a tool, the `SE05x Object Import Application`_. -This tool interfaces with the TEE and gains access to the SE05x to import keys -*and* certificates, as well as listing and removing objects from the secure -element non-volatile memory. +This tool interfaces with the TEE and gains access to the SE05x to import keys *and* certificates. +It can also list and remove objects from the secure element non-volatile memory. -The *certificates* are retrieved in DER format using the APDU interface -presented by the driver, and are then written to the pkcs#11 token. +The *certificates* are retrieved in DER format using the APDU interface presented by the driver, and are then written to the pkcs#11 token. The tool uses `libseteec`_ to send the APDUs to the secure element. and `libckteec`_ to interface with the PKCS#11 implementation. -The `apdu`_ based interface in fact enables privileged user applications to -access the Secure Element. It does this by allowing the normal world to send -APDU frames that encode data and operations to the SE05x using OP-TEE's SCP03 -enabled secure session. +The `apdu`_ based interface enables privileged user applications to access the Secure Element. +It does this by allowing the normal world to send APDU frames. +These encode data and operations to the SE05x using OP-TEE's SCP03 enabled secure session. -Find some usage examples in the note below. Be aware that in OP-TEE's PKCS#11 -implementation **each** PKCS#11 slot is indeed a token. +Find usage examples in the note below. +Be aware that in OP-TEE's PKCS#11 implementation, **each** PKCS#11 slot is indeed a token. .. note:: - Import NXP SE051 Certficate with the id 0xf0000123 into OP-TEE - pkcs#11'aktualizr' token storage: + Import NXP SE051 Certficate with the id 0xf0000123 into OP-TEE pkcs#11'aktualizr' token storage: .. code-block:: none @@ -243,8 +214,7 @@ implementation **each** PKCS#11 slot is indeed a token. $ fio-se05x-cli --show-cert 0xf0000123 --se050 - Import NXP SE051 RSA:2048 bits key with the id 0xf0000123 into OP-TEE - pkcs#11 'aktualizr' token storage: + Import NXP SE051 RSA:2048 bits key with the id 0xf0000123 into OP-TEE pkcs#11 'aktualizr' token storage: .. code-block:: none @@ -271,10 +241,10 @@ The following diagram succintly details the overall design: :width: 6in -A python application that also uses the APDU interface is `ssscli`_, a tool developed by -NXP to provide direct access to its secure element. While it can serve a -purpose during development, it is not required on a deployed product. We -advise deploying with **fio-se05x-cli** and the standard pkcs#11 tools instead. +A python application that also uses the APDU interface is `ssscli`_. +This tool developed by NXP to provide direct access to its secure element. +While it can serve a purpose during development, it is not required on a deployed product. +We advise deploying with ``fio-se05x-cli`` and the standard pkcs#11 tools instead. .. code-block:: none