Commit 5002426e authored by Ahmad Fatoum's avatar Ahmad Fatoum Committed by Jarkko Sakkinen
Browse files

doc: trusted-encrypted: describe new CAAM trust source 



Update documentation for trusted key use with the Cryptographic
Acceleration and Assurance Module (CAAM), an IP on NXP SoCs.

Reviewed-by: default avatarPankaj Gupta <pankaj.gupta@nxp.com>
Reviewed-by: default avatarJarkko Sakkinen <jarkko@kernel.org>
Signed-off-by: default avatarAhmad Fatoum <a.fatoum@pengutronix.de>
Signed-off-by: default avatarJarkko Sakkinen <jarkko@kernel.org>
parent e9c5048c

Documentation/security/keys/trusted-encrypted.rst

+39 −1
Original line number Diff line number Diff line
@@ -35,6 +35,13 @@ safe. 
         Rooted to Hardware Unique Key (HUK) which is generally burnt in on-chip

         fuses and is accessible to TEE only.



     (3) CAAM (Cryptographic Acceleration and Assurance Module: IP on NXP SoCs)



         When High Assurance Boot (HAB) is enabled and the CAAM is in secure

         mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key

         randomly generated and fused into each SoC at manufacturing time.

         Otherwise, a common fixed test key is used instead.



  *  Execution isolation



     (1) TPM
@@ -46,6 +53,10 @@ safe. 
         Customizable set of operations running in isolated execution

         environment verified via Secure/Trusted boot process.



     (3) CAAM



         Fixed set of operations running in isolated execution environment.



  * Optional binding to platform integrity state



     (1) TPM
@@ -63,6 +74,11 @@ safe. 
         Relies on Secure/Trusted boot process for platform integrity. It can

         be extended with TEE based measured boot process.



     (3) CAAM



         Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs

         for platform integrity.



  *  Interfaces and APIs



     (1) TPM
@@ -74,10 +90,13 @@ safe. 
         TEEs have well-documented, standardized client interface and APIs. For

         more details refer to ``Documentation/staging/tee.rst``.



     (3) CAAM



         Interface is specific to silicon vendor.



  *  Threat model



     The strength and appropriateness of a particular TPM or TEE for a given

     The strength and appropriateness of a particular trust source for a given

     purpose must be assessed when using them to protect security-relevant data.
@@ -104,6 +123,12 @@ selected trust source: 
     from platform specific hardware RNG or a software based Fortuna CSPRNG

     which can be seeded via multiple entropy sources.



  *  CAAM: Kernel RNG



     The normal kernel random number generator is used. To seed it from the

     CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device

     is probed.



Users may override this by specifying ``trusted.rng=kernel`` on the kernel

command-line to override the used RNG with the kernel's random number pool.
@@ -193,6 +218,19 @@ Usage:: 
specific to TEE device implementation.  The key length for new keys is always

in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).



Trusted Keys usage: CAAM

------------------------



Usage::



    keyctl add trusted name "new keylen" ring

    keyctl add trusted name "load hex_blob" ring

    keyctl print keyid



"keyctl print" returns an ASCII hex copy of the sealed key, which is in a

CAAM-specific format.  The key length for new keys is always in bytes.

Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).



Encrypted Keys usage

--------------------