[PATCH v7 6/6] docs: trusted-encrypted: add DCP as new trust source

Wed Mar 27 15:40:11 UTC 2024

On Wed Mar 27, 2024 at 10:24 AM EET, David Gstir wrote:
> Update the documentation for trusted and encrypted KEYS with DCP as new
> trust source:
>
> - Describe security properties of DCP trust source
> - Describe key usage
> - Document blob format
>
> Co-developed-by: Richard Weinberger <richard at nod.at>
> Signed-off-by: Richard Weinberger <richard at nod.at>
> Co-developed-by: David Oberhollenzer <david.oberhollenzer at sigma-star.at>
> Signed-off-by: David Oberhollenzer <david.oberhollenzer at sigma-star.at>
> Signed-off-by: David Gstir <david at sigma-star.at>
> ---
>  .../security/keys/trusted-encrypted.rst       | 85 +++++++++++++++++++
>  1 file changed, 85 insertions(+)
>
> diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
> index e989b9802f92..81fb3540bb20 100644
> --- a/Documentation/security/keys/trusted-encrypted.rst
> +++ b/Documentation/security/keys/trusted-encrypted.rst
> @@ -42,6 +42,14 @@ safe.
>           randomly generated and fused into each SoC at manufacturing time.
>           Otherwise, a common fixed test key is used instead.
>  
> +     (4) DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs)
> +
> +         Rooted to a one-time programmable key (OTP) that is generally burnt
> +         in the on-chip fuses and is accessible to the DCP encryption engine only.
> +         DCP provides two keys that can be used as root of trust: the OTP key
> +         and the UNIQUE key. Default is to use the UNIQUE key, but selecting
> +         the OTP key can be done via a module parameter (dcp_use_otp_key).
> +
>    *  Execution isolation
>  
>       (1) TPM
> @@ -57,6 +65,12 @@ safe.
>  
>           Fixed set of operations running in isolated execution environment.
>  
> +     (4) DCP
> +
> +         Fixed set of cryptographic operations running in isolated execution
> +         environment. Only basic blob key encryption is executed there.
> +         The actual key sealing/unsealing is done on main processor/kernel space.
> +
>    * Optional binding to platform integrity state
>  
>       (1) TPM
> @@ -79,6 +93,11 @@ safe.
>           Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs
>           for platform integrity.
>  
> +     (4) DCP
> +
> +         Relies on Secure/Trusted boot process (called HAB by vendor) for
> +         platform integrity.
> +
>    *  Interfaces and APIs
>  
>       (1) TPM
> @@ -94,6 +113,11 @@ safe.
>  
>           Interface is specific to silicon vendor.
>  
> +     (4) DCP
> +
> +         Vendor-specific API that is implemented as part of the DCP crypto driver in
> +         ``drivers/crypto/mxs-dcp.c``.
> +
>    *  Threat model
>  
>       The strength and appropriateness of a particular trust source for a given
> @@ -129,6 +153,13 @@ selected trust source:
>       CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device
>       is probed.
>  
> +  *  DCP (Data Co-Processor: crypto accelerator of various i.MX SoCs)
> +
> +     The DCP hardware device itself does not provide a dedicated RNG interface,
> +     so the kernel default RNG is used. SoCs with DCP like the i.MX6ULL do have
> +     a dedicated hardware RNG that is independent from DCP which can be enabled
> +     to back the kernel RNG.
> +
>  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.
>  
> @@ -231,6 +262,19 @@ Usage::
>  CAAM-specific format.  The key length for new keys is always in bytes.
>  Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
>  
> +Trusted Keys usage: DCP
> +-----------------------
> +
> +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 format
> +specific to this DCP key-blob implementation.  The key length for new keys is
> +always in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
> +
>  Encrypted Keys usage
>  --------------------
>  
> @@ -426,3 +470,44 @@ string length.
>  privkey is the binary representation of TPM2B_PUBLIC excluding the
>  initial TPM2B header which can be reconstructed from the ASN.1 octed
>  string length.
> +
> +DCP Blob Format
> +---------------
> +
> +The Data Co-Processor (DCP) provides hardware-bound AES keys using its
> +AES encryption engine only. It does not provide direct key sealing/unsealing.
> +To make DCP hardware encryption keys usable as trust source, we define
> +our own custom format that uses a hardware-bound key to secure the sealing
> +key stored in the key blob.
> +
> +Whenever a new trusted key using DCP is generated, we generate a random 128-bit
> +blob encryption key (BEK) and 128-bit nonce. The BEK and nonce are used to
> +encrypt the trusted key payload using AES-128-GCM.
> +
> +The BEK itself is encrypted using the hardware-bound key using the DCP's AES
> +encryption engine with AES-128-ECB. The encrypted BEK, generated nonce,
> +BEK-encrypted payload and authentication tag make up the blob format together
> +with a version number, payload length and authentication tag::
> +
> +    /*
> +     * struct dcp_blob_fmt - DCP BLOB format.
> +     *
> +     * @fmt_version: Format version, currently being %1
> +     * @blob_key: Random AES 128 key which is used to encrypt @payload,
> +     *            @blob_key itself is encrypted with OTP or UNIQUE device key in
> +     *            AES-128-ECB mode by DCP.
> +     * @nonce: Random nonce used for @payload encryption.
> +     * @payload_len: Length of the plain text @payload.
> +     * @payload: The payload itself, encrypted using AES-128-GCM and @blob_key,
> +     *           GCM auth tag of size AES_BLOCK_SIZE is attached at the end of it.
> +     *
> +     * The total size of a DCP BLOB is sizeof(struct dcp_blob_fmt) + @payload_len +
> +     * AES_BLOCK_SIZE.
> +     */
> +    struct dcp_blob_fmt {
> +            __u8 fmt_version;
> +            __u8 blob_key[AES_KEYSIZE_128];
> +            __u8 nonce[AES_KEYSIZE_128];
> +            __le32 payload_len;
> +            __u8 payload[];
> +    } __packed;

I'm thinking here given that you need to replicate the same thing that
is in the source files. E.g. Documentation/gpu/i915.rst.

The rationale would so many sources so maybe it would make sense to
maintain this in the source code.

Also this documents how to generally insert documentation inline:
https://docs.kernel.org/doc-guide/kernel-doc.html

I.e. I'm feeling that this is good time to improve scalability so that
documentation will keep up to date. Also then backend specific patches
mostly go to their subdirectories and not to Documentation/ subtree
(or that would be more rare case).

So a good chance to do more than just a new backend for the benefit
of the trusted keys subsystem :-)

Also, later on if something is changed e.g. in the above struct you
don't have to do matching update to the documentation so it will save
time too (over time).

BR, Jarkko