Update documentation for trusted key use with the Cryptographic
Acceleration and Assurance Module (CAAM), an IP on NXP SoCs.
Reviewed-by: Pankaj Gupta <[email protected]>
Signed-off-by: Ahmad Fatoum <[email protected]>
---
v7 -> v8:
- add Pankaj's Reviewed-by
v6 -> v7:
- docs update split off as new Patch (Jarkko)
- fixed typo in "Trusted Keys usage: CAAM" section
To: Jonathan Corbet <[email protected]>
To: David Howells <[email protected]>
To: Jarkko Sakkinen <[email protected]>
To: James Bottomley <[email protected]>
To: Mimi Zohar <[email protected]>
Cc: James Morris <[email protected]>
Cc: "Serge E. Hallyn" <[email protected]>
Cc: "Horia Geantă" <[email protected]>
Cc: Pankaj Gupta <[email protected]>
Cc: Herbert Xu <[email protected]>
Cc: "David S. Miller" <[email protected]>
Cc: Eric Biggers <[email protected]>
Cc: Jan Luebbe <[email protected]>
Cc: David Gstir <[email protected]>
Cc: Richard Weinberger <[email protected]>
Cc: Franck LENORMAND <[email protected]>
Cc: Matthias Schiffer <[email protected]>
Cc: Sumit Garg <[email protected]>
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
Cc: [email protected]
---
.../security/keys/trusted-encrypted.rst | 40 ++++++++++++++++++-
1 file changed, 39 insertions(+), 1 deletion(-)
diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
index 2fe6fd1a2bbd..0bfb4c339748 100644
--- a/Documentation/security/keys/trusted-encrypted.rst
+++ b/Documentation/security/keys/trusted-encrypted.rst
@@ -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
--------------------
--
2.30.2
On Thu, Apr 28, 2022 at 04:01:44PM +0200, Ahmad Fatoum wrote:
> Update documentation for trusted key use with the Cryptographic
> Acceleration and Assurance Module (CAAM), an IP on NXP SoCs.
>
> Reviewed-by: Pankaj Gupta <[email protected]>
> Signed-off-by: Ahmad Fatoum <[email protected]>
> ---
> v7 -> v8:
> - add Pankaj's Reviewed-by
> v6 -> v7:
> - docs update split off as new Patch (Jarkko)
> - fixed typo in "Trusted Keys usage: CAAM" section
>
> To: Jonathan Corbet <[email protected]>
> To: David Howells <[email protected]>
> To: Jarkko Sakkinen <[email protected]>
> To: James Bottomley <[email protected]>
> To: Mimi Zohar <[email protected]>
> Cc: James Morris <[email protected]>
> Cc: "Serge E. Hallyn" <[email protected]>
> Cc: "Horia Geantă" <[email protected]>
> Cc: Pankaj Gupta <[email protected]>
> Cc: Herbert Xu <[email protected]>
> Cc: "David S. Miller" <[email protected]>
> Cc: Eric Biggers <[email protected]>
> Cc: Jan Luebbe <[email protected]>
> Cc: David Gstir <[email protected]>
> Cc: Richard Weinberger <[email protected]>
> Cc: Franck LENORMAND <[email protected]>
> Cc: Matthias Schiffer <[email protected]>
> Cc: Sumit Garg <[email protected]>
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> Cc: [email protected]
> ---
> .../security/keys/trusted-encrypted.rst | 40 ++++++++++++++++++-
> 1 file changed, 39 insertions(+), 1 deletion(-)
>
> diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
> index 2fe6fd1a2bbd..0bfb4c339748 100644
> --- a/Documentation/security/keys/trusted-encrypted.rst
> +++ b/Documentation/security/keys/trusted-encrypted.rst
> @@ -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
> --------------------
>
> --
> 2.30.2
>
Reviewed-by: Jarkko Sakkinen <[email protected]>
BR, Jarkko