From: Sumit Garg <sumit.garg@linaro.org>
To: keyrings@vger.kernel.org, linux-integrity@vger.kernel.org,
linux-security-module@vger.kernel.org
Cc: jens.wiklander@linaro.org, corbet@lwn.net, dhowells@redhat.com,
jejb@linux.ibm.com, jarkko.sakkinen@linux.intel.com,
zohar@linux.ibm.com, jmorris@namei.org, serge@hallyn.com,
casey@schaufler-ca.com, ard.biesheuvel@linaro.org,
daniel.thompson@linaro.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org,
linux-arm-kernel@lists.infradead.org, tee-dev@lists.linaro.org,
Sumit Garg <sumit.garg@linaro.org>
Subject: [RFC v2 5/6] doc: keys: Document usage of TEE based Trusted Keys
Date: Tue, 30 Jul 2019 17:53:39 +0530 [thread overview]
Message-ID: <1564489420-677-6-git-send-email-sumit.garg@linaro.org> (raw)
In-Reply-To: <1564489420-677-1-git-send-email-sumit.garg@linaro.org>
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@linaro.org>
---
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
next prev parent reply other threads:[~2019-07-30 12:25 UTC|newest]
Thread overview: 27+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-30 12:23 [RFC v2 0/6] Introduce TEE based Trusted Keys support Sumit Garg
2019-07-30 12:23 ` [RFC v2 1/6] tee: optee: allow kernel pages to register as shm Sumit Garg
2019-07-30 12:23 ` [RFC v2 2/6] tee: enable support to register kernel memory Sumit Garg
2019-08-08 22:26 ` [Tee-dev] " Stuart Yoder
2019-08-09 5:36 ` Sumit Garg
2019-07-30 12:23 ` [RFC v2 3/6] tee: add private login method for kernel clients Sumit Garg
2019-07-30 12:23 ` [RFC v2 4/6] KEYS: trusted: Introduce TEE based Trusted Keys Sumit Garg
2019-07-30 12:23 ` Sumit Garg [this message]
2019-07-30 12:23 ` [RFC v2 6/6] MAINTAINERS: Add entry for " Sumit Garg
2019-07-31 7:11 ` [RFC v2 0/6] Introduce TEE based Trusted Keys support Janne Karhunen
2019-07-31 10:21 ` Janne Karhunen
2019-07-31 13:58 ` Sumit Garg
2019-08-01 6:21 ` Janne Karhunen
2019-08-01 7:40 ` Sumit Garg
2019-08-01 7:59 ` Janne Karhunen
2019-08-01 10:00 ` Sumit Garg
2019-08-01 10:40 ` Janne Karhunen
2019-07-31 10:26 ` Sumit Garg
2019-07-31 11:02 ` Janne Karhunen
2019-07-31 14:23 ` Sumit Garg
2019-08-01 6:36 ` Janne Karhunen
2019-08-01 6:50 ` [Tee-dev] " Rouven Czerwinski
2019-08-01 7:30 ` Janne Karhunen
2019-08-01 7:58 ` Sumit Garg
2019-08-01 8:30 ` Janne Karhunen
2019-08-01 10:27 ` Sumit Garg
2019-08-04 20:48 ` Jarkko Sakkinen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1564489420-677-6-git-send-email-sumit.garg@linaro.org \
--to=sumit.garg@linaro.org \
--cc=ard.biesheuvel@linaro.org \
--cc=casey@schaufler-ca.com \
--cc=corbet@lwn.net \
--cc=daniel.thompson@linaro.org \
--cc=dhowells@redhat.com \
--cc=jarkko.sakkinen@linux.intel.com \
--cc=jejb@linux.ibm.com \
--cc=jens.wiklander@linaro.org \
--cc=jmorris@namei.org \
--cc=keyrings@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-integrity@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-security-module@vger.kernel.org \
--cc=serge@hallyn.com \
--cc=tee-dev@lists.linaro.org \
--cc=zohar@linux.ibm.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).