Commit 28c5f596 authored by David Gstir's avatar David Gstir Committed by Jarkko Sakkinen
Browse files

docs: trusted-encrypted: add DCP as new trust source 



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: default avatarRichard Weinberger <richard@nod.at>
Signed-off-by: default avatarRichard Weinberger <richard@nod.at>
Co-developed-by: default avatarDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>
Signed-off-by: default avatarDavid Oberhollenzer <david.oberhollenzer@sigma-star.at>
Signed-off-by: default avatarDavid Gstir <david@sigma-star.at>
Reviewed-by: default avatarJarkko Sakkinen <jarkko@kernel.org>
Reviewed-by: default avatarBagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: default avatarJarkko Sakkinen <jarkko@kernel.org>
parent b85b253e

Documentation/security/keys/trusted-encrypted.rst

+53 −0
Original line number Diff line number Diff line
@@ -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

security/keys/trusted-keys/trusted_dcp.c

+19 −0
Original line number Diff line number Diff line
@@ -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.

 *