On Thu Mar 28, 2024 at 8:47 PM EET, Jarkko Sakkinen wrote:
> On Thu Mar 28, 2024 at 10:05 AM EET, David Gstir wrote:
> > Jarkko,
> >
> > > On 27.03.2024, at 16:40, Jarkko Sakkinen <jar...@kernel.org> wrote:
> > >
> > > 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 <rich...@nod.at>
> > >> Signed-off-by: Richard Weinberger <rich...@nod.at>
> > >> Co-developed-by: David Oberhollenzer <david.oberhollen...@sigma-star.at>
> > >> Signed-off-by: David Oberhollenzer <david.oberhollen...@sigma-star.at>
> > >> Signed-off-by: David Gstir <da...@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).
> >
> > sound good! I’ll maintain the blob format documentation to the source and
> > insert
> > a reference in the documentation. Thanks for pointing that out!
> >
> > Is there anything else I can improve for this patchset? I’d like to include
> > that in v8
> > too and make it the last iteration of this patchset.
>
> Yeah, I don't enforce you to convert all the existing work to this
> model, but we could use this as a reference for that work.
I mean that way documentation update will become more natural part of
the code update and less frustrating to do which usually encourages
to document stuff better and also later on tweak and improve it.
So yeah I feel that GPU documentation in kernel is doing lot's of things
right, and other subsystems should follow. I.e. it is good reference
model for trusted keys documentation, and said I'm cool with realizing
this for only this new key type :-) Otherwise, finishing this patch set
will torture for you and also for me if it tries to fix everything.
BR, Jarkko
