summaryrefslogtreecommitdiffstats
path: root/Documentation/security/keys/trusted-encrypted.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/security/keys/trusted-encrypted.rst')
-rw-r--r--Documentation/security/keys/trusted-encrypted.rst428
1 files changed, 428 insertions, 0 deletions
diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst
new file mode 100644
index 0000000000..9bc9db8ec6
--- /dev/null
+++ b/Documentation/security/keys/trusted-encrypted.rst
@@ -0,0 +1,428 @@
+==========================
+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.
+
+
+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)
+
+ When High Assurance Boot (HAB) is enabled and the CAAM is in secure
+ mode, trust is rooted to the OTPMK, a never-disclosed 256-bit key
+ randomly generated and fused into each SoC at manufacturing time.
+ Otherwise, a common fixed test key is used instead.
+
+ * 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.
+
+ (3) CAAM
+
+ Fixed set of operations running in isolated execution environment.
+
+ * 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.
+
+ (3) CAAM
+
+ Relies on the High Assurance Boot (HAB) mechanism of NXP SoCs
+ for platform integrity.
+
+ * 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``.
+
+ (3) CAAM
+
+ Interface is specific to silicon vendor.
+
+ * Threat model
+
+ The strength and appropriateness of a particular trust source 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. 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. The random number generator in use differs according to the
+selected trust source:
+
+ * TPM: hardware device based RNG
+
+ Keys are generated within the TPM. 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.
+
+ * CAAM: Kernel RNG
+
+ The normal kernel random number generator is used. To seed it from the
+ CAAM HWRNG, enable CRYPTO_DEV_FSL_CAAM_RNG_API and ensure the device
+ is probed.
+
+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.
+
+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 either from kernel-generated
+random numbers or user-provided decrypted data, 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::
+
+ #> tsscreateprimary -hi o -st
+ Handle 80000000
+ #> tssevictcontrol -hi o -ho 80000000 -hp 81000001
+
+Or with the Intel TSS 2 stack::
+
+ #> tpm2_createprimary --hierarchy o -G rsa2048 -c key.ctxt
+ [...]
+ #> tpm2_evictcontrol -c key.ctxt 0x81000001
+ persistentHandle: 0x81000001
+
+Usage::
+
+ keyctl add trusted name "new keylen [options]" ring
+ keyctl add trusted name "load hex_blob [pcrlock=pcrnum]" ring
+ keyctl update key "update [options]"
+ keyctl print keyid
+
+ options:
+ keyhandle= ascii hex value of sealing key
+ TPM 1.2: default 0x40000000 (SRK)
+ TPM 2.0: no default; must be passed every time
+ keyauth= ascii hex auth for sealing key default 0x00...i
+ (40 ascii zeros)
+ blobauth= ascii hex auth for sealed data default 0x00...
+ (40 ascii zeros)
+ pcrinfo= ascii hex of PCR_INFO or PCR_INFO_LONG (no default)
+ pcrlock= pcr number to be extended to "lock" blob
+ migratable= 0|1 indicating permission to reseal to new PCR values,
+ default 1 (resealing allowed)
+ hash= hash algorithm name as a string. For TPM 1.x the only
+ allowed value is sha1. For TPM 2.x the allowed values
+ are sha1, sha256, sha384, sha512 and sm3-256.
+ policydigest= digest for the authorization policy. must be calculated
+ with the same hash algorithm as specified by the 'hash='
+ option.
+ policyhandle= handle to an authorization policy session that defines the
+ same policy and with the same hash algorithm as was used to
+ seal the key.
+
+"keyctl print" returns an ascii hex copy of the sealed key, which is in standard
+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
+within the 2048 bit SRK (RSA) keylength, with all necessary structure/padding.
+
+Trusted Keys usage: TEE
+-----------------------
+
+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 TEE device implementation. The key length for new keys is always
+in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
+
+Trusted Keys usage: CAAM
+------------------------
+
+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 a
+CAAM-specific format. 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
+key or a more complex structure. The format of the more complex structure is
+application specific, which is identified by 'format'.
+
+Usage::
+
+ keyctl add encrypted name "new [format] key-type:master-key-name keylen"
+ ring
+ keyctl add encrypted name "new [format] key-type:master-key-name keylen
+ decrypted-data" ring
+ keyctl add encrypted name "load hex_blob" ring
+ keyctl update keyid "update key-type:master-key-name"
+
+Where::
+
+ format:= 'default | ecryptfs | enc32'
+ key-type:= 'trusted' | 'user'
+
+Examples of trusted and encrypted key usage
+-------------------------------------------
+
+Create and save a trusted key named "kmk" of length 32 bytes.
+
+Note: When using a TPM 2.0 with a persistent key with handle 0x81000001,
+append 'keyhandle=0x81000001' to statements between quotes, such as
+"new 32 keyhandle=0x81000001".
+
+::
+
+ $ keyctl add trusted kmk "new 32" @u
+ 440502848
+
+ $ keyctl show
+ Session Keyring
+ -3 --alswrv 500 500 keyring: _ses
+ 97833714 --alswrv 500 -1 \_ keyring: _uid.500
+ 440502848 --alswrv 500 500 \_ trusted: kmk
+
+ $ keyctl print 440502848
+ 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
+ 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
+ 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
+ a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
+ d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
+ dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
+ f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
+ e4a8aea2b607ec96931e6f4d4fe563ba
+
+ $ keyctl pipe 440502848 > kmk.blob
+
+Load a trusted key from the saved blob::
+
+ $ keyctl add trusted kmk "load `cat kmk.blob`" @u
+ 268728824
+
+ $ keyctl print 268728824
+ 0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
+ 3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
+ 27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
+ a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
+ d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
+ dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
+ f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
+ e4a8aea2b607ec96931e6f4d4fe563ba
+
+Reseal (TPM specific) a trusted key under new PCR values::
+
+ $ keyctl update 268728824 "update pcrinfo=`cat pcr.blob`"
+ $ keyctl print 268728824
+ 010100000000002c0002800093c35a09b70fff26e7a98ae786c641e678ec6ffb6b46d805
+ 77c8a6377aed9d3219c6dfec4b23ffe3000001005d37d472ac8a44023fbb3d18583a4f73
+ d3a076c0858f6f1dcaa39ea0f119911ff03f5406df4f7f27f41da8d7194f45c9f4e00f2e
+ df449f266253aa3f52e55c53de147773e00f0f9aca86c64d94c95382265968c354c5eab4
+ 9638c5ae99c89de1e0997242edfb0b501744e11ff9762dfd951cffd93227cc513384e7e6
+ e782c29435c7ec2edafaa2f4c1fe6e7a781b59549ff5296371b42133777dcc5b8b971610
+ 94bc67ede19e43ddb9dc2baacad374a36feaf0314d700af0a65c164b7082401740e489c9
+ 7ef6a24defe4846104209bf0c3eced7fa1a672ed5b125fc9d8cd88b476a658a4434644ef
+ df8ae9a178e9f83ba9f08d10fa47e4226b98b0702f06b3b8
+
+
+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
+trusted key provides strong guarantees that the EVM key has not been
+compromised by a user level problem, and when sealed to a platform integrity
+state, protects against boot and offline attacks. Create and save an
+encrypted key "evm" using the above trusted key "kmk":
+
+option 1: omitting 'format'::
+
+ $ keyctl add encrypted evm "new trusted:kmk 32" @u
+ 159771175
+
+option 2: explicitly defining 'format' as 'default'::
+
+ $ keyctl add encrypted evm "new default trusted:kmk 32" @u
+ 159771175
+
+ $ keyctl print 159771175
+ default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3
+ 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0
+ 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc
+
+ $ keyctl pipe 159771175 > evm.blob
+
+Load an encrypted key "evm" from saved blob::
+
+ $ keyctl add encrypted evm "load `cat evm.blob`" @u
+ 831684262
+
+ $ keyctl print 831684262
+ default trusted:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b3
+ 82dbbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0
+ 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc
+
+Instantiate an encrypted key "evm" using user-provided decrypted data::
+
+ $ evmkey=$(dd if=/dev/urandom bs=1 count=32 | xxd -c32 -p)
+ $ keyctl add encrypted evm "new default user:kmk 32 $evmkey" @u
+ 794890253
+
+ $ keyctl print 794890253
+ default user:kmk 32 2375725ad57798846a9bbd240de8906f006e66c03af53b1b382d
+ bbc55be2a44616e4959430436dc4f2a7a9659aa60bb4652aeb2120f149ed197c564e0247
+ 17c64 5972dcb82ab2dde83376d82b2e3c09ffc
+
+Other uses for trusted and encrypted keys, such as for disk and file encryption
+are anticipated. In particular the new format 'ecryptfs' has been defined
+in order to use encrypted keys to mount an eCryptfs filesystem. More details
+about the usage can be found in the file
+``Documentation/security/keys/ecryptfs.rst``.
+
+Another new format 'enc32' has been defined in order to support encrypted keys
+with payload size of 32 bytes. This will initially be used for nvdimm security
+but may expand to other usages that require 32 bytes payload.
+
+
+TPM 2.0 ASN.1 Key Format
+------------------------
+
+The TPM 2.0 ASN.1 key format is designed to be easily recognisable,
+even in binary form (fixing a problem we had with the TPM 1.2 ASN.1
+format) and to be extensible for additions like importable keys and
+policy::
+
+ TPMKey ::= SEQUENCE {
+ type OBJECT IDENTIFIER
+ emptyAuth [0] EXPLICIT BOOLEAN OPTIONAL
+ parent INTEGER
+ pubkey OCTET STRING
+ privkey OCTET STRING
+ }
+
+type is what distinguishes the key even in binary form since the OID
+is provided by the TCG to be unique and thus forms a recognizable
+binary pattern at offset 3 in the key. The OIDs currently made
+available are::
+
+ 2.23.133.10.1.3 TPM Loadable key. This is an asymmetric key (Usually
+ RSA2048 or Elliptic Curve) which can be imported by a
+ TPM2_Load() operation.
+
+ 2.23.133.10.1.4 TPM Importable Key. This is an asymmetric key (Usually
+ RSA2048 or Elliptic Curve) which can be imported by a
+ TPM2_Import() operation.
+
+ 2.23.133.10.1.5 TPM Sealed Data. This is a set of data (up to 128
+ bytes) which is sealed by the TPM. It usually
+ represents a symmetric key and must be unsealed before
+ use.
+
+The trusted key code only uses the TPM Sealed Data OID.
+
+emptyAuth is true if the key has well known authorization "". If it
+is false or not present, the key requires an explicit authorization
+phrase. This is used by most user space consumers to decide whether
+to prompt for a password.
+
+parent represents the parent key handle, either in the 0x81 MSO space,
+like 0x81000001 for the RSA primary storage key. Userspace programmes
+also support specifying the primary handle in the 0x40 MSO space. If
+this happens the Elliptic Curve variant of the primary key using the
+TCG defined template will be generated on the fly into a volatile
+object and used as the parent. The current kernel code only supports
+the 0x81 MSO form.
+
+pubkey is the binary representation of TPM2B_PRIVATE excluding the
+initial TPM2B header, which can be reconstructed from the ASN.1 octet
+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.