Provide documentation for usage of TEE based Trusted Keys via existing
user-space "keyctl" utility. Also, document various use-cases.
Signed-off-by: Sumit Garg <sumit.garg@xxxxxxxxxx>
---
Documentation/security/keys/index.rst | 1 +
Documentation/security/keys/tee-trusted.rst | 93 +++++++++++++++++++++++++++++
2 files changed, 94 insertions(+)
create mode 100644 Documentation/security/keys/tee-trusted.rst
diff --git a/Documentation/security/keys/index.rst b/Documentation/security/keys/index.rst
index 647d58f..f9ef557 100644
--- a/Documentation/security/keys/index.rst
+++ b/Documentation/security/keys/index.rst
@@ -9,3 +9,4 @@ Kernel Keys
ecryptfs
request-key
trusted-encrypted
+ tee-trusted
diff --git a/Documentation/security/keys/tee-trusted.rst b/Documentation/security/keys/tee-trusted.rst
new file mode 100644
index 0000000..ef03745
--- /dev/null
+++ b/Documentation/security/keys/tee-trusted.rst
@@ -0,0 +1,93 @@
+======================
+TEE based Trusted Keys
+======================
+
+TEE based Trusted Keys provides an alternative approach for providing Trusted
+Keys in case TPM chip isn't present.
+
+Trusted Keys use a TEE service/device both to generate and to seal the keys.
+Keys are sealed under a hardware unique key in the TEE, and only unsealed by
+the TEE.
+
+For more information about TEE, refer to ``Documentation/tee.txt``.
+
+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 are always
+in bytes. Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
+
+Examples of trusted key and its usage as 'master' key for encrypted key usage:
+
+More details about encrypted keys can be found here:
+``Documentation/security/keys/trusted-encrypted.rst``
+
+Create and save a trusted key named "kmk" of length 32 bytes::
+
+ $ keyctl add trusted kmk "new 32" @u
+ 754414669
+
+ $ keyctl show
+ Session Keyring
+ 827385718 --alswrv 0 65534 keyring: _uid_ses.0
+ 274124851 --alswrv 0 65534 \_ keyring: _uid.0
+ 754414669 --als-rv 0 0 \_ trusted: kmk
+
+ $ keyctl print 754414669
+ 15676790697861b422175596ae001c2f505cea2c6f3ebbc5fb08eeb1f343a07e
+
+ $ keyctl pipe 754414669 > kmk.blob
+
+Load a trusted key from the saved blob::
+
+ $ keyctl add trusted kmk "load `cat kmk.blob`" @u
+ 491638700
+
+ $ keyctl print 491638700
+ 15676790697861b422175596ae001c2f505cea2c6f3ebbc5fb08eeb1f343a07e
+
+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
+TEE based trusted key provides security that the EVM key has not been
+compromised by a user level problem and tied to particular hardware.
+
+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
+ 608915065
+
+option 2: explicitly defining 'format' as 'default'::
+
+ $ keyctl add encrypted evm "new default trusted:kmk 32" @u
+ 608915065
+
+ $ keyctl print 608915065
+ default trusted:kmk 32 f380ac588a925f488d5be007cf23e4c900b8b652ab62241c8
+ ed54906189b6659d139d619d4b51752a2645537b11fd44673f13154a65b3f595d5fb2131
+ 2fe45529ea0407c644ea4026f2a1a75661f2c9b66
+
+ $ keyctl pipe 608915065 > 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 f380ac588a925f488d5be007cf23e4c900b8b652ab62241c8
+ ed54906189b6659d139d619d4b51752a2645537b11fd44673f13154a65b3f595d5fb2131
+ 2fe45529ea0407c644ea4026f2a1a75661f2c9b66
+
+Other uses for trusted and encrypted keys, such as for disk and file encryption
+are anticipated. In particular the 'ecryptfs' encrypted keys format can be used
+to mount an eCryptfs filesystem. More details about the usage can be found in
+the file ``Documentation/security/keys/ecryptfs.rst``.
+
+Another format 'enc32' can be used to support encrypted keys with payload size
+of 32 bytes.
--
2.7.4
