linux-kernel.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
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


  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).