| Message ID | 1572530323-14802-7-git-send-email-sumit.garg@linaro.org |
|---|---|
| State | New |
| Headers | show |
| Series | Introduce TEE based Trusted Keys support | expand |
On Thu, Oct 31, 2019 at 07:28:42PM +0530, Sumit Garg wrote: > 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> This is the most important commit in order for someone who don't deal that much with ARM TEE to get right. Until this commit is right, I don't unfortunately have much to say about other commits. Instead of making disjoint islands, you should edit trusted-encrypted.rst so that it describes commonalities and differences. What the document currently describes is the usage model. It could be a section of its own. In that you should describe first the common parameters and separetely the backend specific parametrs. From kernel internals (there could be a section with this name) the document describe the key generation e.g. is the hardware used and how it is used, is there salting with krng and so forth. /Jarkko
On Fri, 1 Nov 2019 at 03:17, Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> wrote: > > On Thu, Oct 31, 2019 at 07:28:42PM +0530, Sumit Garg wrote: > > 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> > > This is the most important commit in order for someone who don't deal > that much with ARM TEE to get right. > I agree that documentation needs to be updated and your following comments seems to be somewhat similar to comments from Mimi here [1]. > Until this commit is right, I don't > unfortunately have much to say about other commits. Isn't this statement contradicting with your earlier statement regarding the right order would be to complete TEE patches review first and then come up with documentation here [2]? [1] https://lore.kernel.org/linux-integrity/1568025601.4614.253.camel@linux.ibm.com/ [2] https://lore.kernel.org/linux-integrity/20190909163643.qxmzpcggi567hmhv@linux.intel.com/ > Instead of making disjoint islands, you should edit trusted-encrypted.rst > so that it describes commonalities and differences. > > What the document currently describes is the usage model. It could be a > section of its own. In that you should describe first the common > parameters and separetely the backend specific parametrs. > > From kernel internals (there could be a section with this name) the > document describe the key generation e.g. is the hardware used and how > it is used, is there salting with krng and so forth. BTW, here is the info regarding RNG provided by OP-TEE (an open-source TEE implementation). It's either direct output from hardware based RNG (if platform supports one) [3] or a software based Fortuna CSPRNG (executing in trusted environment) [4] which is seeded via multiple entropy sources as described here [5]. Overall, I think salting this with krng sounds reasonable to address single RNG source concern. So I would suggest to have a common wrapper API that would do salting of trust source (TPM or TEE) RNG output with krng. [3] https://github.com/OP-TEE/optee_os/blob/master/core/crypto/rng_hw.c [4] https://github.com/OP-TEE/optee_os/blob/master/core/crypto/rng_fortuna.c [5] https://github.com/OP-TEE/optee_os/blob/master/core/include/crypto/crypto.h#L272 -Sumit > > /Jarkko
On Fri, Nov 01, 2019 at 03:04:18PM +0530, Sumit Garg wrote: > Isn't this statement contradicting with your earlier statement > regarding the right order would be to complete TEE patches review > first and then come up with documentation here [2]? > > [1] https://lore.kernel.org/linux-integrity/1568025601.4614.253.camel@linux.ibm.com/ > [2] https://lore.kernel.org/linux-integrity/20190909163643.qxmzpcggi567hmhv@linux.intel.com/ With the intersecting issues, namely key generation and conflicting keyctl parameters, that was not a well considered statement. /Jarkko
On Sat, 2 Nov 2019 at 01:50, Jarkko Sakkinen <jarkko.sakkinen@linux.intel.com> wrote: > > On Fri, Nov 01, 2019 at 03:04:18PM +0530, Sumit Garg wrote: > > > Isn't this statement contradicting with your earlier statement > > regarding the right order would be to complete TEE patches review > > first and then come up with documentation here [2]? > > > > [1] https://lore.kernel.org/linux-integrity/1568025601.4614.253.camel@linux.ibm.com/ > > [2] https://lore.kernel.org/linux-integrity/20190909163643.qxmzpcggi567hmhv@linux.intel.com/ > > With the intersecting issues, namely key generation and conflicting > keyctl parameters, that was not a well considered statement. Okay, let me work on documentation first, but I think resending whole patch-set just for documentation review and rework would be an overkill. Would minor revisions of this patch only like v3.1, v3.2 etc. work for you? And later I could send next version of this patch-set once we agree on documentation. -Sumit > > /Jarkko
On Mon, Nov 04, 2019 at 12:28:47PM +0530, Sumit Garg wrote: > On Sat, 2 Nov 2019 at 01:50, Jarkko Sakkinen > <jarkko.sakkinen@linux.intel.com> wrote: > > > > On Fri, Nov 01, 2019 at 03:04:18PM +0530, Sumit Garg wrote: > > > > > Isn't this statement contradicting with your earlier statement > > > regarding the right order would be to complete TEE patches review > > > first and then come up with documentation here [2]? > > > > > > [1] https://lore.kernel.org/linux-integrity/1568025601.4614.253.camel@linux.ibm.com/ > > > [2] https://lore.kernel.org/linux-integrity/20190909163643.qxmzpcggi567hmhv@linux.intel.com/ > > > > With the intersecting issues, namely key generation and conflicting > > keyctl parameters, that was not a well considered statement. > > Okay, let me work on documentation first, but I think resending whole > patch-set just for documentation review and rework would be an > overkill. Would minor revisions of this patch only like v3.1, v3.2 > etc. work for you? And later I could send next version of this > patch-set once we agree on documentation. Yeah, we could iterate through the documentation patch and once we are happy with it you can bundle it to your main patch set. /Jarkko
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.
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 -- 2.7.4