[v8,6/6] docs: trusted-encrypted: add DCP as new trust source

Commit Message

David Gstir April 3, 2024, 7:21 a.m. UTC

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 <[e-mail]>
Signed-off-by: Richard Weinberger <[e-mail]>
Co-developed-by: David Oberhollenzer <[e-mail]>
Signed-off-by: David Oberhollenzer <[e-mail]>
Signed-off-by: David Gstir <[e-mail]>
---
 .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
 security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
 2 files changed, 72 insertions(+)

Comments

Bagas Sanjaya April 3, 2024, 1:24 p.m. UTC | #1

On Wed, Apr 03, 2024 at 09:21:22AM +0200, David Gstir wrote:
> diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
> index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
> +---------------
> +
> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> +   :doc: dcp blob format
> +
> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> +   :identifiers: struct dcp_blob_fmt
> diff --git a/security/keys/trusted-keys/trusted_dcp.c b/security/keys/trusted-keys/trusted_dcp.c
> index 16c44aafeab3..b5f81a05be36 100644
> --- a/security/keys/trusted-keys/trusted_dcp.c
> +++ b/security/keys/trusted-keys/trusted_dcp.c
> @@ -19,6 +19,25 @@
>  #define DCP_BLOB_VERSION 1
>  #define DCP_BLOB_AUTHLEN 16
>  
> +/**
> + * DOC: 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.
>   *

The doc LGTM, thanks!

Reviewed-by: Bagas Sanjaya <[e-mail]>

Jarkko Sakkinen April 3, 2024, 3:47 p.m. UTC | #2

On Wed Apr 3, 2024 at 10:21 AM EEST, 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 <[e-mail]>
> Signed-off-by: Richard Weinberger <[e-mail]>
> Co-developed-by: David Oberhollenzer <[e-mail]>
> Signed-off-by: David Oberhollenzer <[e-mail]>
> Signed-off-by: David Gstir <[e-mail]>
> ---
>  .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
>  security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
>  2 files changed, 72 insertions(+)
>
> diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
> index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
> +---------------
> +
> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> +   :doc: dcp blob format
> +
> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> +   :identifiers: struct dcp_blob_fmt
> diff --git a/security/keys/trusted-keys/trusted_dcp.c b/security/keys/trusted-keys/trusted_dcp.c
> index 16c44aafeab3..b5f81a05be36 100644
> --- a/security/keys/trusted-keys/trusted_dcp.c
> +++ b/security/keys/trusted-keys/trusted_dcp.c
> @@ -19,6 +19,25 @@
>  #define DCP_BLOB_VERSION 1
>  #define DCP_BLOB_AUTHLEN 16
>  
> +/**
> + * DOC: 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.
>   *

Reviewed-by: Jarkko Sakkinen <[e-mail]>

I can only test that this does not break a machine without the
hardware feature.

Is there anyone who could possibly peer test these patches?

BR, Jarkko

Kshitiz Varshney April 9, 2024, 9:48 a.m. UTC | #3

Hi Jarkko,


> -----Original Message-----
> From: Jarkko Sakkinen <[e-mail]>
> Sent: Wednesday, April 3, 2024 9:18 PM
> To: David Gstir <[e-mail]>; Mimi Zohar <[e-mail]>;
> James Bottomley <[e-mail]>; Herbert Xu
> <[e-mail]>; David S. Miller <[e-mail]>
> Cc: Shawn Guo <[e-mail]>; Jonathan Corbet
> <[e-mail]>; Sascha Hauer <[e-mail]>; Pengutronix
> Kernel Team <[e-mail]>; Fabio Estevam
> <[e-mail]>; dl-linux-imx <[e-mail]>; Ahmad Fatoum
> <[e-mail]>; sigma star Kernel Team
> <[e-mail]>; David Howells <[e-mail]>; Li
> Yang <[e-mail]>; Paul Moore <[e-mail]>; James
> Morris <[e-mail]>; Serge E. Hallyn <[e-mail]>; Paul E.
> McKenney <[e-mail]>; Randy Dunlap <[e-mail]>;
> Catalin Marinas <[e-mail]>; Rafael J. Wysocki
> <[e-mail]>; Tejun Heo <[e-mail]>; Steven Rostedt
> (Google) <[e-mail]>; [e-mail]; linux-
> [e-mail]; [e-mail];
> [e-mail]; [e-mail]; linux-arm-
> [e-mail]; [e-mail]; linux-security-
> [e-mail]; Richard Weinberger <[e-mail]>; David
> Oberhollenzer <[e-mail]>
> Subject: [EXT] Re: [PATCH v8 6/6] docs: trusted-encrypted: add DCP as new
> trust source
> 
> Caution: This is an external email. Please take care when clicking links or
> opening attachments. When in doubt, report the message using the 'Report
> this email' button
> 
> 
> On Wed Apr 3, 2024 at 10:21 AM EEST, 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 <[e-mail]>
> > Signed-off-by: Richard Weinberger <[e-mail]>
> > Co-developed-by: David Oberhollenzer
> > <[e-mail]>
> > Signed-off-by: David Oberhollenzer <[e-mail]>
> > Signed-off-by: David Gstir <[e-mail]>
> > ---
> >  .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
> >  security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
> >  2 files changed, 72 insertions(+)
> >
> > diff --git a/Documentation/security/keys/trusted-encrypted.rst
> > b/Documentation/security/keys/trusted-encrypted.rst
> > index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
> > +---------------
> > +
> > +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> > +   :doc: dcp blob format
> > +
> > +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> > +   :identifiers: struct dcp_blob_fmt
> > diff --git a/security/keys/trusted-keys/trusted_dcp.c
> > b/security/keys/trusted-keys/trusted_dcp.c
> > index 16c44aafeab3..b5f81a05be36 100644
> > --- a/security/keys/trusted-keys/trusted_dcp.c
> > +++ b/security/keys/trusted-keys/trusted_dcp.c
> > @@ -19,6 +19,25 @@
> >  #define DCP_BLOB_VERSION 1
> >  #define DCP_BLOB_AUTHLEN 16
> >
> > +/**
> > + * DOC: 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.
> >   *
> 
> Reviewed-by: Jarkko Sakkinen <[e-mail]>
> 
> I can only test that this does not break a machine without the hardware
> feature.
> 
> Is there anyone who could possibly peer test these patches?
I am already working on testing this patchset on i.MX6 platform.
Regards,
Kshitiz
> BR, Jarkko

Herbert Xu April 12, 2024, 6:26 a.m. UTC | #4

On Wed, Apr 03, 2024 at 06:47:51PM +0300, Jarkko Sakkinen wrote:
>
> Reviewed-by: Jarkko Sakkinen <[e-mail]>
> 
> I can only test that this does not break a machine without the
> hardware feature.

Please feel free to take this through your tree.

Thanks,

Jarkko Sakkinen April 13, 2024, 9:24 p.m. UTC | #5

On Tue Apr 9, 2024 at 12:48 PM EEST, Kshitiz Varshney wrote:
> Hi Jarkko,
>
>
> > -----Original Message-----
> > From: Jarkko Sakkinen <[e-mail]>
> > Sent: Wednesday, April 3, 2024 9:18 PM
> > To: David Gstir <[e-mail]>; Mimi Zohar <[e-mail]>;
> > James Bottomley <[e-mail]>; Herbert Xu
> > <[e-mail]>; David S. Miller <[e-mail]>
> > Cc: Shawn Guo <[e-mail]>; Jonathan Corbet
> > <[e-mail]>; Sascha Hauer <[e-mail]>; Pengutronix
> > Kernel Team <[e-mail]>; Fabio Estevam
> > <[e-mail]>; dl-linux-imx <[e-mail]>; Ahmad Fatoum
> > <[e-mail]>; sigma star Kernel Team
> > <[e-mail]>; David Howells <[e-mail]>; Li
> > Yang <[e-mail]>; Paul Moore <[e-mail]>; James
> > Morris <[e-mail]>; Serge E. Hallyn <[e-mail]>; Paul E.
> > McKenney <[e-mail]>; Randy Dunlap <[e-mail]>;
> > Catalin Marinas <[e-mail]>; Rafael J. Wysocki
> > <[e-mail]>; Tejun Heo <[e-mail]>; Steven Rostedt
> > (Google) <[e-mail]>; [e-mail]; linux-
> > [e-mail]; [e-mail];
> > [e-mail]; [e-mail]; linux-arm-
> > [e-mail]; [e-mail]; linux-security-
> > [e-mail]; Richard Weinberger <[e-mail]>; David
> > Oberhollenzer <[e-mail]>
> > Subject: [EXT] Re: [PATCH v8 6/6] docs: trusted-encrypted: add DCP as new
> > trust source
> > 
> > Caution: This is an external email. Please take care when clicking links or
> > opening attachments. When in doubt, report the message using the 'Report
> > this email' button
> > 
> > 
> > On Wed Apr 3, 2024 at 10:21 AM EEST, 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 <[e-mail]>
> > > Signed-off-by: Richard Weinberger <[e-mail]>
> > > Co-developed-by: David Oberhollenzer
> > > <[e-mail]>
> > > Signed-off-by: David Oberhollenzer <[e-mail]>
> > > Signed-off-by: David Gstir <[e-mail]>
> > > ---
> > >  .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
> > >  security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
> > >  2 files changed, 72 insertions(+)
> > >
> > > diff --git a/Documentation/security/keys/trusted-encrypted.rst
> > > b/Documentation/security/keys/trusted-encrypted.rst
> > > index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
> > > +---------------
> > > +
> > > +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> > > +   :doc: dcp blob format
> > > +
> > > +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> > > +   :identifiers: struct dcp_blob_fmt
> > > diff --git a/security/keys/trusted-keys/trusted_dcp.c
> > > b/security/keys/trusted-keys/trusted_dcp.c
> > > index 16c44aafeab3..b5f81a05be36 100644
> > > --- a/security/keys/trusted-keys/trusted_dcp.c
> > > +++ b/security/keys/trusted-keys/trusted_dcp.c
> > > @@ -19,6 +19,25 @@
> > >  #define DCP_BLOB_VERSION 1
> > >  #define DCP_BLOB_AUTHLEN 16
> > >
> > > +/**
> > > + * DOC: 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.
> > >   *
> > 
> > Reviewed-by: Jarkko Sakkinen <[e-mail]>
> > 
> > I can only test that this does not break a machine without the hardware
> > feature.
> > 
> > Is there anyone who could possibly peer test these patches?
> I am already working on testing this patchset on i.MX6 platform.
> Regards,
> Kshitiz

OK great.

BR, Jarkko

Jarkko Sakkinen April 13, 2024, 9:44 p.m. UTC | #6

On Fri Apr 12, 2024 at 9:26 AM EEST, Herbert Xu wrote:
> On Wed, Apr 03, 2024 at 06:47:51PM +0300, Jarkko Sakkinen wrote:
> >
> > Reviewed-by: Jarkko Sakkinen <[e-mail]>
> > 
> > I can only test that this does not break a machine without the
> > hardware feature.
>
> Please feel free to take this through your tree.
>
> Thanks,

OK, thanks!

BR, Jarkko

David Gstir April 29, 2024, 11:35 a.m. UTC | #7

Hi Kshitiz,

> On 09.04.2024, at 11:48, Kshitiz Varshney <[e-mail]> wrote:
> 
> Hi Jarkko,
> 
> 
>> -----Original Message-----
>> From: Jarkko Sakkinen <[e-mail]>
>> Sent: Wednesday, April 3, 2024 9:18 PM
>> To: David Gstir <[e-mail]>; Mimi Zohar <[e-mail]>;
>> James Bottomley <[e-mail]>; Herbert Xu
>> <[e-mail]>; David S. Miller <[e-mail]>
>> Cc: Shawn Guo <[e-mail]>; Jonathan Corbet
>> <[e-mail]>; Sascha Hauer <[e-mail]>; Pengutronix
>> Kernel Team <[e-mail]>; Fabio Estevam
>> <[e-mail]>; dl-linux-imx <[e-mail]>; Ahmad Fatoum
>> <[e-mail]>; sigma star Kernel Team
>> <[e-mail]>; David Howells <[e-mail]>; Li
>> Yang <[e-mail]>; Paul Moore <[e-mail]>; James
>> Morris <[e-mail]>; Serge E. Hallyn <[e-mail]>; Paul E.
>> McKenney <[e-mail]>; Randy Dunlap <[e-mail]>;
>> Catalin Marinas <[e-mail]>; Rafael J. Wysocki
>> <[e-mail]>; Tejun Heo <[e-mail]>; Steven Rostedt
>> (Google) <[e-mail]>; [e-mail]; linux-
>> [e-mail]; [e-mail];
>> [e-mail]; [e-mail]; linux-arm-
>> [e-mail]; [e-mail]; linux-security-
>> [e-mail]; Richard Weinberger <[e-mail]>; David
>> Oberhollenzer <[e-mail]>
>> Subject: [EXT] Re: [PATCH v8 6/6] docs: trusted-encrypted: add DCP as new
>> trust source
>> 
>> Caution: This is an external email. Please take care when clicking links or
>> opening attachments. When in doubt, report the message using the 'Report
>> this email' button
>> 
>> 
>> On Wed Apr 3, 2024 at 10:21 AM EEST, 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 <[e-mail]>
>>> Signed-off-by: Richard Weinberger <[e-mail]>
>>> Co-developed-by: David Oberhollenzer
>>> <[e-mail]>
>>> Signed-off-by: David Oberhollenzer <[e-mail]>
>>> Signed-off-by: David Gstir <[e-mail]>
>>> ---
>>> .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
>>> security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
>>> 2 files changed, 72 insertions(+)
>>> 
>>> diff --git a/Documentation/security/keys/trusted-encrypted.rst
>>> b/Documentation/security/keys/trusted-encrypted.rst
>>> index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
>>> +---------------
>>> +
>>> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
>>> +   :doc: dcp blob format
>>> +
>>> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
>>> +   :identifiers: struct dcp_blob_fmt
>>> diff --git a/security/keys/trusted-keys/trusted_dcp.c
>>> b/security/keys/trusted-keys/trusted_dcp.c
>>> index 16c44aafeab3..b5f81a05be36 100644
>>> --- a/security/keys/trusted-keys/trusted_dcp.c
>>> +++ b/security/keys/trusted-keys/trusted_dcp.c
>>> @@ -19,6 +19,25 @@
>>> #define DCP_BLOB_VERSION 1
>>> #define DCP_BLOB_AUTHLEN 16
>>> 
>>> +/**
>>> + * DOC: 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.
>>>  *
>> 
>> Reviewed-by: Jarkko Sakkinen <[e-mail]>
>> 
>> I can only test that this does not break a machine without the hardware
>> feature.
>> 
>> Is there anyone who could possibly peer test these patches?
> I am already working on testing this patchset on i.MX6 platform.

Did you get around to testing this?
I’d greatly appreciate a Tested-by for this. :-)

Thanks!
BR, David

Kshitiz Varshney April 30, 2024, 11:48 a.m. UTC | #8

Hi David,

> -----Original Message-----
> From: David Gstir <[e-mail]>
> Sent: Monday, April 29, 2024 5:05 PM
> To: Kshitiz Varshney <[e-mail]>
> Cc: Jarkko Sakkinen <[e-mail]>; Mimi Zohar
> <[e-mail]>; James Bottomley <[e-mail]>; Herbert
> Xu <[e-mail]>; David S. Miller
> <[e-mail]>; Shawn Guo <[e-mail]>; Jonathan
> Corbet <[e-mail]>; Sascha Hauer <[e-mail]>;
> [e-mail]; Fabio Estevam <[e-mail]>; dl-linux-imx
> <[e-mail]>; Ahmad Fatoum <[e-mail]>; sigma
> star Kernel Team <[e-mail]>; David Howells
> <[e-mail]>; Li Yang <[e-mail]>; Paul Moore
> <[e-mail]>; James Morris <[e-mail]>; Serge E.
> Hallyn <[e-mail]>; Paul E. McKenney <[e-mail]>;
> Randy Dunlap <[e-mail]>; Catalin Marinas
> <[e-mail]>; Rafael J. Wysocki
> <[e-mail]>; Tejun Heo <[e-mail]>; Steven Rostedt
> (Google) <[e-mail]>; [e-mail]; linux-
> [e-mail]; [e-mail];
> [e-mail]; [e-mail]; linux-arm-
> [e-mail]; [e-mail]; linux-security-
> [e-mail]; Richard Weinberger <[e-mail]>; David
> Oberhollenzer <[e-mail]>; Varun Sethi
> <[e-mail]>; Gaurav Jain <[e-mail]>; Pankaj Gupta
> <[e-mail]>
> Subject: Re: [EXT] [PATCH v8 6/6] docs: trusted-encrypted: add DCP as new
> trust source
> 
> Caution: This is an external email. Please take care when clicking links or
> opening attachments. When in doubt, report the message using the 'Report
> this email' button
> 
> 
> Hi Kshitiz,
> 
> > On 09.04.2024, at 11:48, Kshitiz Varshney <[e-mail]>
> wrote:
> >
> > Hi Jarkko,
> >
> >
> >> -----Original Message-----
> >> From: Jarkko Sakkinen <[e-mail]>
> >> Sent: Wednesday, April 3, 2024 9:18 PM
> >> To: David Gstir <[e-mail]>; Mimi Zohar
> >> <[e-mail]>; James Bottomley <[e-mail]>;
> Herbert
> >> Xu <[e-mail]>; David S. Miller
> >> <[e-mail]>
> >> Cc: Shawn Guo <[e-mail]>; Jonathan Corbet
> >> <[e-mail]>; Sascha Hauer <[e-mail]>;
> Pengutronix
> >> Kernel Team <[e-mail]>; Fabio Estevam
> >> <[e-mail]>; dl-linux-imx <[e-mail]>; Ahmad
> Fatoum
> >> <[e-mail]>; sigma star Kernel Team
> >> <[e-mail]>; David Howells <[e-mail]>;
> Li
> >> Yang <[e-mail]>; Paul Moore <[e-mail]>;
> James
> >> Morris <[e-mail]>; Serge E. Hallyn <[e-mail]>; Paul
> E.
> >> McKenney <[e-mail]>; Randy Dunlap
> <[e-mail]>;
> >> Catalin Marinas <[e-mail]>; Rafael J. Wysocki
> >> <[e-mail]>; Tejun Heo <[e-mail]>; Steven
> >> Rostedt
> >> (Google) <[e-mail]>; [e-mail]; linux-
> >> [e-mail]; [e-mail];
> >> [e-mail]; [e-mail]; linux-arm-
> >> [e-mail]; [e-mail];
> >> linux-security- [e-mail]; Richard Weinberger
> >> <[e-mail]>; David Oberhollenzer
> >> <[e-mail]>
> >> Subject: [EXT] Re: [PATCH v8 6/6] docs: trusted-encrypted: add DCP as
> >> new trust source
> >>
> >> Caution: This is an external email. Please take care when clicking
> >> links or opening attachments. When in doubt, report the message using
> >> the 'Report this email' button
> >>
> >>
> >> On Wed Apr 3, 2024 at 10:21 AM EEST, 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 <[e-mail]>
> >>> Signed-off-by: Richard Weinberger <[e-mail]>
> >>> Co-developed-by: David Oberhollenzer
> >>> <[e-mail]>
> >>> Signed-off-by: David Oberhollenzer
> >>> <[e-mail]>
> >>> Signed-off-by: David Gstir <[e-mail]>
> >>> ---
> >>> .../security/keys/trusted-encrypted.rst       | 53 +++++++++++++++++++
> >>> security/keys/trusted-keys/trusted_dcp.c      | 19 +++++++
> >>> 2 files changed, 72 insertions(+)
> >>>
> >>> diff --git a/Documentation/security/keys/trusted-encrypted.rst
> >>> b/Documentation/security/keys/trusted-encrypted.rst
> >>> index e989b9802f92..f4d7e162d5e4 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,12 @@ 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
> >>> +---------------
> >>> +
> >>> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> >>> +   :doc: dcp blob format
> >>> +
> >>> +.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
> >>> +   :identifiers: struct dcp_blob_fmt
> >>> diff --git a/security/keys/trusted-keys/trusted_dcp.c
> >>> b/security/keys/trusted-keys/trusted_dcp.c
> >>> index 16c44aafeab3..b5f81a05be36 100644
> >>> --- a/security/keys/trusted-keys/trusted_dcp.c
> >>> +++ b/security/keys/trusted-keys/trusted_dcp.c
> >>> @@ -19,6 +19,25 @@
> >>> #define DCP_BLOB_VERSION 1
> >>> #define DCP_BLOB_AUTHLEN 16
> >>>
> >>> +/**
> >>> + * DOC: 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.
> >>>  *
> >>
> >> Reviewed-by: Jarkko Sakkinen <[e-mail]>
> >>
> >> I can only test that this does not break a machine without the
> >> hardware feature.
> >>
> >> Is there anyone who could possibly peer test these patches?
> > I am already working on testing this patchset on i.MX6 platform.
> 
> Did you get around to testing this?
> I’d greatly appreciate a Tested-by for this. :-)
> 
> Thanks!
> BR, David

Currently, I am bit busy with other priority activities. It will take time to test this patch set.

Regards,
Kshitiz

David Gstir April 30, 2024, 12:03 p.m. UTC | #9

Hi Jarkko,

> On 30.04.2024, at 13:48, Kshitiz Varshney <[e-mail]> wrote:
> 
> Hi David,
> 
>> -----Original Message-----
>> From: David Gstir <[e-mail]>
>> Sent: Monday, April 29, 2024 5:05 PM
>> To: Kshitiz Varshney <[e-mail]>


>> 
>> Did you get around to testing this?
>> I’d greatly appreciate a Tested-by for this. :-)
>> 
>> Thanks!
>> BR, David
> 
> Currently, I am bit busy with other priority activities. It will take time to test this patch set.

How should we proceed here?
Do we have to miss another release cycle, because of a Tested-by?

If any bugs pop up I’ll happily fix them, but at the moment it appears to be more of a formality.
IMHO the patch set itself is rather small and has been thoroughly reviewed to ensure that any huge
issues would already have been caught by now.

Thanks!
BR, David

Jarkko Sakkinen May 3, 2024, 11:45 p.m. UTC | #10

On Tue Apr 30, 2024 at 3:03 PM EEST, David Gstir wrote:
> Hi Jarkko,
>
> > On 30.04.2024, at 13:48, Kshitiz Varshney <[e-mail]> wrote:
> > 
> > Hi David,
> > 
> >> -----Original Message-----
> >> From: David Gstir <[e-mail]>
> >> Sent: Monday, April 29, 2024 5:05 PM
> >> To: Kshitiz Varshney <[e-mail]>
>
>
> >> 
> >> Did you get around to testing this?
> >> I’d greatly appreciate a Tested-by for this. :-)
> >> 
> >> Thanks!
> >> BR, David
> > 
> > Currently, I am bit busy with other priority activities. It will take time to test this patch set.
>
> How should we proceed here?
> Do we have to miss another release cycle, because of a Tested-by?
>
> If any bugs pop up I’ll happily fix them, but at the moment it appears to be more of a formality.
> IMHO the patch set itself is rather small and has been thoroughly reviewed to ensure that any huge
> issues would already have been caught by now.

I don't mind picking this actually since unless you consume it,
it should not get in the way. I'll pick it during the weekend.
Thanks for reminding.

BR, Jarkko

Patch

diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
index e989b9802f92..f4d7e162d5e4 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,12 @@  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
+---------------
+
+.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
+   :doc: dcp blob format
+
+.. kernel-doc:: security/keys/trusted-keys/trusted_dcp.c
+   :identifiers: struct dcp_blob_fmt
diff --git a/security/keys/trusted-keys/trusted_dcp.c b/security/keys/trusted-keys/trusted_dcp.c
index 16c44aafeab3..b5f81a05be36 100644
--- a/security/keys/trusted-keys/trusted_dcp.c
+++ b/security/keys/trusted-keys/trusted_dcp.c
@@ -19,6 +19,25 @@ 
 #define DCP_BLOB_VERSION 1
 #define DCP_BLOB_AUTHLEN 16
 
+/**
+ * DOC: 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.
  *