Documentation/security/keys/trusted-encrypted.rst

Source file repositories/reference/linux-study-clean/Documentation/security/keys/trusted-encrypted.rst

File Facts

System
Linux kernel
Corpus path
Documentation/security/keys/trusted-encrypted.rst
Extension
.rst
Size
24551 bytes
Lines
618
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

==========================
Trusted and Encrypted Keys
==========================

Trusted and Encrypted Keys are two new key types added to the existing kernel
key ring service.  Both of these new types are variable length symmetric keys,
and in both cases all keys are created in the kernel, and user space sees,
stores, and loads only encrypted blobs.  Trusted Keys require the availability
of a Trust Source for greater security, while Encrypted Keys can be used on any
system. All user level blobs, are displayed and loaded in hex ASCII for
convenience, and are integrity verified.

Trusted Keys as Protected key
=============================
It is the secure way of keeping the keys in the kernel key-ring as Trusted-Key,
such that:

- Key-blob, an encrypted key-data, created to be stored, loaded and seen by
  userspace.
- Key-data, the plain-key text in the system memory, to be used by
  kernel space only.

Though key-data is not accessible to the user-space in plain-text, but it is in
plain-text in system memory, when used in kernel space. Even though kernel-space
attracts small surface attack, but with compromised kernel or side-channel
attack accessing the system memory can lead to a chance of the key getting
compromised/leaked.

In order to protect the key in kernel space, the concept of "protected-keys" is
introduced which will act as an added layer of protection. The key-data of the
protected keys is encrypted with Key-Encryption-Key(KEK), and decrypted inside
the trust source boundary. The plain-key text never available out-side in the
system memory. Thus, any crypto operation that is to be executed using the
protected key, can only be done by the trust source, which generated the
key blob.

Hence, if the protected-key is leaked or compromised, it is of no use to the
hacker.

Trusted keys as protected keys, with trust source having the capability of
generating:

- Key-Blob, to be loaded, stored and seen by user-space.

Trust Source
============

A trust source provides the source of security for Trusted Keys.  This
section lists currently supported trust sources, along with their security
considerations.  Whether or not a trust source is sufficiently safe depends
on the strength and correctness of its implementation, as well as the threat
environment for a specific use case.  Since the kernel doesn't know what the
environment is, and there is no metric of trust, it is dependent on the
consumer of the Trusted Keys to determine if the trust source is sufficiently
safe.

  *  Root of trust for storage

     (1) TPM (Trusted Platform Module: hardware device)

         Rooted to Storage Root Key (SRK) which never leaves the TPM that
         provides crypto operation to establish root of trust for storage.

     (2) TEE (Trusted Execution Environment: OP-TEE based on Arm TrustZone)

         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)

Annotation

Implementation Notes