doc: trusted-encrypted: updates with TEE as a new trust source
Update documentation for Trusted and Encrypted Keys with TEE as a new trust source. Following is brief description of updates: - Add a section to demonstrate a list of supported devices along with their security properties/guarantees. - Add a key generation section. - Updates for usage section including differences specific to a trust source. Co-developed-by: Elaine Palmer <erpalmer@us.ibm.com> Signed-off-by: Elaine Palmer <erpalmer@us.ibm.com> Signed-off-by: Sumit Garg <sumit.garg@linaro.org> Signed-off-by: Jarkko Sakkinen <jarkko@kernel.org>
This commit is contained in:
parent
0a95ebc913
commit
c429805fdf
@ -6,30 +6,127 @@ 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,
|
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,
|
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
|
stores, and loads only encrypted blobs. Trusted Keys require the availability
|
||||||
of a Trusted Platform Module (TPM) chip for greater security, while Encrypted
|
of a Trust Source for greater security, while Encrypted Keys can be used on any
|
||||||
Keys can be used on any system. All user level blobs, are displayed and loaded
|
system. All user level blobs, are displayed and loaded in hex ASCII for
|
||||||
in hex ascii for convenience, and are integrity verified.
|
convenience, and are integrity verified.
|
||||||
|
|
||||||
Trusted Keys use a TPM both to generate and to seal the keys. Keys are sealed
|
|
||||||
under a 2048 bit RSA key in the TPM, and optionally sealed to specified PCR
|
|
||||||
(integrity measurement) values, and only unsealed by the TPM, if PCRs and blob
|
|
||||||
integrity verifications match. A loaded Trusted Key can be updated with new
|
|
||||||
(future) PCR values, so keys are easily migrated to new pcr values, such as
|
|
||||||
when the kernel and initramfs are updated. The same key can have many saved
|
|
||||||
blobs under different PCR values, so multiple boots are easily supported.
|
|
||||||
|
|
||||||
TPM 1.2
|
Trust Source
|
||||||
-------
|
============
|
||||||
|
|
||||||
By default, trusted keys are sealed under the SRK, which has the default
|
A trust source provides the source of security for Trusted Keys. This
|
||||||
authorization value (20 zeros). This can be set at takeownership time with the
|
section lists currently supported trust sources, along with their security
|
||||||
trouser's utility: "tpm_takeownership -u -z".
|
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.
|
||||||
|
|
||||||
TPM 2.0
|
* Root of trust for storage
|
||||||
-------
|
|
||||||
|
|
||||||
The user must first create a storage key and make it persistent, so the key is
|
(1) TPM (Trusted Platform Module: hardware device)
|
||||||
available after reboot. This can be done using the following commands.
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
* Execution isolation
|
||||||
|
|
||||||
|
(1) TPM
|
||||||
|
|
||||||
|
Fixed set of operations running in isolated execution environment.
|
||||||
|
|
||||||
|
(2) TEE
|
||||||
|
|
||||||
|
Customizable set of operations running in isolated execution
|
||||||
|
environment verified via Secure/Trusted boot process.
|
||||||
|
|
||||||
|
* Optional binding to platform integrity state
|
||||||
|
|
||||||
|
(1) TPM
|
||||||
|
|
||||||
|
Keys can be optionally sealed to specified PCR (integrity measurement)
|
||||||
|
values, and only unsealed by the TPM, if PCRs and blob integrity
|
||||||
|
verifications match. A loaded Trusted Key can be updated with new
|
||||||
|
(future) PCR values, so keys are easily migrated to new PCR values,
|
||||||
|
such as when the kernel and initramfs are updated. The same key can
|
||||||
|
have many saved blobs under different PCR values, so multiple boots are
|
||||||
|
easily supported.
|
||||||
|
|
||||||
|
(2) TEE
|
||||||
|
|
||||||
|
Relies on Secure/Trusted boot process for platform integrity. It can
|
||||||
|
be extended with TEE based measured boot process.
|
||||||
|
|
||||||
|
* Interfaces and APIs
|
||||||
|
|
||||||
|
(1) TPM
|
||||||
|
|
||||||
|
TPMs have well-documented, standardized interfaces and APIs.
|
||||||
|
|
||||||
|
(2) TEE
|
||||||
|
|
||||||
|
TEEs have well-documented, standardized client interface and APIs. For
|
||||||
|
more details refer to ``Documentation/staging/tee.rst``.
|
||||||
|
|
||||||
|
|
||||||
|
* Threat model
|
||||||
|
|
||||||
|
The strength and appropriateness of a particular TPM or TEE for a given
|
||||||
|
purpose must be assessed when using them to protect security-relevant data.
|
||||||
|
|
||||||
|
|
||||||
|
Key Generation
|
||||||
|
==============
|
||||||
|
|
||||||
|
Trusted Keys
|
||||||
|
------------
|
||||||
|
|
||||||
|
New keys are created from random numbers generated in the trust source. They
|
||||||
|
are encrypted/decrypted using a child key in the storage key hierarchy.
|
||||||
|
Encryption and decryption of the child key must be protected by a strong
|
||||||
|
access control policy within the trust source.
|
||||||
|
|
||||||
|
* TPM (hardware device) based RNG
|
||||||
|
|
||||||
|
Strength of random numbers may vary from one device manufacturer to
|
||||||
|
another.
|
||||||
|
|
||||||
|
* TEE (OP-TEE based on Arm TrustZone) based RNG
|
||||||
|
|
||||||
|
RNG is customizable as per platform needs. It can either be direct output
|
||||||
|
from platform specific hardware RNG or a software based Fortuna CSPRNG
|
||||||
|
which can be seeded via multiple entropy sources.
|
||||||
|
|
||||||
|
Encrypted Keys
|
||||||
|
--------------
|
||||||
|
|
||||||
|
Encrypted keys do not depend on a trust source, and are faster, as they use AES
|
||||||
|
for encryption/decryption. New keys are created from kernel-generated random
|
||||||
|
numbers, and are encrypted/decrypted using a specified ‘master’ key. The
|
||||||
|
‘master’ key can either be a trusted-key or user-key type. The main disadvantage
|
||||||
|
of encrypted keys is that if they are not rooted in a trusted key, they are only
|
||||||
|
as secure as the user key encrypting them. The master user key should therefore
|
||||||
|
be loaded in as secure a way as possible, preferably early in boot.
|
||||||
|
|
||||||
|
|
||||||
|
Usage
|
||||||
|
=====
|
||||||
|
|
||||||
|
Trusted Keys usage: TPM
|
||||||
|
-----------------------
|
||||||
|
|
||||||
|
TPM 1.2: By default, trusted keys are sealed under the SRK, which has the
|
||||||
|
default authorization value (20 bytes of 0s). This can be set at takeownership
|
||||||
|
time with the TrouSerS utility: "tpm_takeownership -u -z".
|
||||||
|
|
||||||
|
TPM 2.0: The user must first create a storage key and make it persistent, so the
|
||||||
|
key is available after reboot. This can be done using the following commands.
|
||||||
|
|
||||||
With the IBM TSS 2 stack::
|
With the IBM TSS 2 stack::
|
||||||
|
|
||||||
@ -78,14 +175,21 @@ TPM_STORED_DATA format. The key length for new keys are always in bytes.
|
|||||||
Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit
|
Trusted Keys can be 32 - 128 bytes (256 - 1024 bits), the upper limit is to fit
|
||||||
within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.
|
within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.
|
||||||
|
|
||||||
Encrypted keys do not depend on a TPM, and are faster, as they use AES for
|
Trusted Keys usage: TEE
|
||||||
encryption/decryption. New keys are created from kernel generated random
|
-----------------------
|
||||||
numbers, and are encrypted/decrypted using a specified 'master' key. The
|
|
||||||
'master' key can either be a trusted-key or user-key type. The main
|
Usage::
|
||||||
disadvantage of encrypted keys is that if they are not rooted in a trusted key,
|
|
||||||
they are only as secure as the user key encrypting them. The master user key
|
keyctl add trusted name "new keylen" ring
|
||||||
should therefore be loaded in as secure a way as possible, preferably early in
|
keyctl add trusted name "load hex_blob" ring
|
||||||
boot.
|
keyctl print keyid
|
||||||
|
|
||||||
|
"keyctl print" returns an ASCII hex copy of the sealed key, which is in format
|
||||||
|
specific to TEE device implementation. The key length for new keys is always
|
||||||
|
in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
|
||||||
|
|
||||||
|
Encrypted Keys usage
|
||||||
|
--------------------
|
||||||
|
|
||||||
The decrypted portion of encrypted keys can contain either a simple symmetric
|
The decrypted portion of encrypted keys can contain either a simple symmetric
|
||||||
key or a more complex structure. The format of the more complex structure is
|
key or a more complex structure. The format of the more complex structure is
|
||||||
@ -103,8 +207,8 @@ Where::
|
|||||||
format:= 'default | ecryptfs | enc32'
|
format:= 'default | ecryptfs | enc32'
|
||||||
key-type:= 'trusted' | 'user'
|
key-type:= 'trusted' | 'user'
|
||||||
|
|
||||||
|
Examples of trusted and encrypted key usage
|
||||||
Examples of trusted and encrypted key usage:
|
-------------------------------------------
|
||||||
|
|
||||||
Create and save a trusted key named "kmk" of length 32 bytes.
|
Create and save a trusted key named "kmk" of length 32 bytes.
|
||||||
|
|
||||||
@ -150,7 +254,7 @@ Load a trusted key from the saved blob::
|
|||||||
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
|
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
|
||||||
e4a8aea2b607ec96931e6f4d4fe563ba
|
e4a8aea2b607ec96931e6f4d4fe563ba
|
||||||
|
|
||||||
Reseal a trusted key under new pcr values::
|
Reseal (TPM specific) a trusted key under new PCR values::
|
||||||
|
|
||||||
$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
|
$ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
|
||||||
$ keyctl print 268728824
|
$ keyctl print 268728824
|
||||||
@ -164,11 +268,12 @@ Reseal a trusted key under new pcr values::
|
|||||||
7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef
|
7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef
|
||||||
df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8
|
df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8
|
||||||
|
|
||||||
|
|
||||||
The initial consumer of trusted keys is EVM, which at boot time needs a high
|
The initial consumer of trusted keys is EVM, which at boot time needs a high
|
||||||
quality symmetric key for HMAC protection of file metadata. The use of a
|
quality symmetric key for HMAC protection of file metadata. The use of a
|
||||||
trusted key provides strong guarantees that the EVM key has not been
|
trusted key provides strong guarantees that the EVM key has not been
|
||||||
compromised by a user level problem, and when sealed to specific boot PCR
|
compromised by a user level problem, and when sealed to a platform integrity
|
||||||
values, protects against boot and offline attacks. Create and save an
|
state, protects against boot and offline attacks. Create and save an
|
||||||
encrypted key "evm" using the above trusted key "kmk":
|
encrypted key "evm" using the above trusted key "kmk":
|
||||||
|
|
||||||
option 1: omitting 'format'::
|
option 1: omitting 'format'::
|
||||||
|
Loading…
Reference in New Issue
Block a user