Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: trusted-encrypted: trusted-keys as protected keys
Add a section in trusted key document describing the protected-keys.
- Detailing need for protected keys.
- Detailing the usage for protected keys.
Signed-off-by: Pankaj Gupta <pankaj.gupta@nxp.com>
Signed-off-by: Meenakshi Aggarwal <meenakshi.aggarwal@nxp.com>
Signed-off-by: Herbert Xu <herbert@gondor.apana.org.au>
authored by
Meenakshi Aggarwal
and committed by
Herbert Xu
38f68807
4f3b5f9e
+86
-1
+86
-1
Documentation/security/keys/trusted-encrypted.rst
+86
-1
Documentation/security/keys/trusted-encrypted.rst
···
10
10
system. All user level blobs, are displayed and loaded in hex ASCII for
11
11
convenience, and are integrity verified.
12
12
13
+
Trusted Keys as Protected key
14
+
=============================
15
+
It is the secure way of keeping the keys in the kernel key-ring as Trusted-Key,
16
+
such that:
17
+
- Key-blob, an encrypted key-data, created to be stored, loaded and seen by
18
+
userspace.
19
+
- Key-data, the plain-key text in the system memory, to be used by
20
+
kernel space only.
21
+
22
+
Though key-data is not accessible to the user-space in plain-text, but it is in
23
+
plain-text in system memory, when used in kernel space. Even though kernel-space
24
+
attracts small surface attack, but with compromised kernel or side-channel
25
+
attack accessing the system memory can lead to a chance of the key getting
26
+
compromised/leaked.
27
+
28
+
In order to protect the key in kernel space, the concept of "protected-keys" is
29
+
introduced which will act as an added layer of protection. The key-data of the
30
+
protected keys is encrypted with Key-Encryption-Key(KEK), and decrypted inside
31
+
the trust source boundary. The plain-key text never available out-side in the
32
+
system memory. Thus, any crypto operation that is to be executed using the
33
+
protected key, can only be done by the trust source, which generated the
34
+
key blob.
35
+
36
+
Hence, if the protected-key is leaked or compromised, it is of no use to the
37
+
hacker.
38
+
39
+
Trusted keys as protected keys, with trust source having the capability of
40
+
generating:
41
+
42
+
- Key-Blob, to be loaded, stored and seen by user-space.
13
43
14
44
Trust Source
15
45
============
···
282
252
Trusted Keys usage: CAAM
283
253
------------------------
284
254
285
-
Usage::
255
+
Trusted Keys Usage::
286
256
287
257
keyctl add trusted name "new keylen" ring
288
258
keyctl add trusted name "load hex_blob" ring
289
259
keyctl print keyid
260
+
261
+
"keyctl print" returns an ASCII hex copy of the sealed key, which is in a
262
+
CAAM-specific format. The key length for new keys is always in bytes.
263
+
Trusted Keys can be 32 - 128 bytes (256 - 1024 bits).
264
+
265
+
Trusted Keys as Protected Keys Usage::
266
+
267
+
keyctl add trusted name "new keylen pk [options]" ring
268
+
keyctl add trusted name "load hex_blob [options]" ring
269
+
keyctl print keyid
270
+
271
+
where, 'pk' is used to direct trust source to generate protected key.
272
+
273
+
options:
274
+
key_enc_algo = For CAAM, supported enc algo are ECB(2), CCM(1).
290
275
291
276
"keyctl print" returns an ASCII hex copy of the sealed key, which is in a
292
277
CAAM-specific format. The key length for new keys is always in bytes.
···
376
331
Load a trusted key from the saved blob::
377
332
378
333
$ keyctl add trusted kmk "load `cat kmk.blob`" @u
334
+
268728824
335
+
336
+
$ keyctl print 268728824
337
+
0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
338
+
3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
339
+
27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
340
+
a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
341
+
d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
342
+
dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
343
+
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
344
+
e4a8aea2b607ec96931e6f4d4fe563ba
345
+
346
+
Create and save a trusted key as protected key named "kmk" of length 32 bytes.
347
+
348
+
::
349
+
350
+
$ keyctl add trusted kmk "new 32 pk key_enc_algo=1" @u
351
+
440502848
352
+
353
+
$ keyctl show
354
+
Session Keyring
355
+
-3 --alswrv 500 500 keyring: _ses
356
+
97833714 --alswrv 500 -1 \_ keyring: _uid.500
357
+
440502848 --alswrv 500 500 \_ trusted: kmk
358
+
359
+
$ keyctl print 440502848
360
+
0101000000000000000001005d01b7e3f4a6be5709930f3b70a743cbb42e0cc95e18e915
361
+
3f60da455bbf1144ad12e4f92b452f966929f6105fd29ca28e4d4d5a031d068478bacb0b
362
+
27351119f822911b0a11ba3d3498ba6a32e50dac7f32894dd890eb9ad578e4e292c83722
363
+
a52e56a097e6a68b3f56f7a52ece0cdccba1eb62cad7d817f6dc58898b3ac15f36026fec
364
+
d568bd4a706cb60bb37be6d8f1240661199d640b66fb0fe3b079f97f450b9ef9c22c6d5d
365
+
dd379f0facd1cd020281dfa3c70ba21a3fa6fc2471dc6d13ecf8298b946f65345faa5ef0
366
+
f1f8fff03ad0acb083725535636addb08d73dedb9832da198081e5deae84bfaf0409c22b
367
+
e4a8aea2b607ec96931e6f4d4fe563ba
368
+
369
+
$ keyctl pipe 440502848 > kmk.blob
370
+
371
+
Load a trusted key from the saved blob::
372
+
373
+
$ keyctl add trusted kmk "load `cat kmk.blob` key_enc_algo=1" @u
379
374
268728824
380
375
381
376
$ keyctl print 268728824