diff options
| author | Udit Agarwal <udit.agarwal@nxp.com> | 2018-07-04 09:51:59 +0530 |
|---|---|---|
| committer | Dong Aisheng <aisheng.dong@nxp.com> | 2019-11-25 15:43:20 +0800 |
| commit | e2173ee9874b74843341562659ba15593f33ed72 (patch) | |
| tree | 24ce324224ebcd4a47a71f149959b3610298546d /Documentation/security | |
| parent | 219d54332a09e8d8741c1e1982f5eae56099de85 (diff) | |
security/keys/secure_key: Adds the secure key support based on CAAM.
Secure keys are derieved using CAAM crypto block.
Secure keys derieved are the random number symmetric keys from CAAM.
Blobs corresponding to the key are formed using CAAM. User space
will only be able to view the blob of the key.
Signed-off-by: Udit Agarwal <udit.agarwal@nxp.com>
Reviewed-by: Sahil Malhotra <sahil.malhotra@nxp.com>
Diffstat (limited to 'Documentation/security')
| -rw-r--r-- | Documentation/security/keys/secure-key.rst | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/Documentation/security/keys/secure-key.rst b/Documentation/security/keys/secure-key.rst new file mode 100644 index 000000000000..a33ffd09d7bd --- /dev/null +++ b/Documentation/security/keys/secure-key.rst @@ -0,0 +1,67 @@ +========== +Secure Key +========== + +Secure key is the new type added to kernel key ring service. +Secure key is a symmetric type key of minimum length 32 bytes +and with maximum possible length to be 128 bytes. It is produced +in kernel using the CAAM crypto engine. Userspace can only see +the blob for the corresponding key. All the blobs are displayed +or loaded in hex ascii. + +Secure key can be created on platforms which supports CAAM +hardware block. Secure key can also be used as a master key to +create the encrypted keys along with the existing key types in +kernel. + +Secure key uses CAAM hardware to generate the key and blobify its +content for userspace. Generated blobs are tied up with the hardware +secret key stored in CAAM, hence the same blob will not be able to +de-blobify with the different secret key on another machine. + +Usage:: + + keyctl add secure <name> "new <keylen>" <ring> + keyctl load secure <name> "load <hex_blob>" <ring> + keyctl print <key_id> + +"keyctl add secure" option will create the random data of the +specified key len using CAAM and store it as a key in kernel. +Key contents will be displayed as blobs to the user in hex ascii. +User can input key len from 32 bytes to 128 bytes. + +"keyctl load secure" option will load the blob contents. In kernel, +key will be deirved using input blob and CAAM, along with the secret +key stored in CAAM. + +"keyctl print" will return the hex string of the blob corresponding to +key_id. Returned blob will be of key_len + 48 bytes. Extra 48 bytes are +the header bytes added by the CAAM. + +Example of secure key usage:: + +1. Create the secure key with name kmk-master of length 32 bytes:: + + $ keyctl add secure kmk-master "new 32" @u + 46001928 + + $keyctl show + Session Keyring + 1030783626 --alswrv 0 65534 keyring: _uid_ses.0 + 695927745 --alswrv 0 65534 \_ keyring: _uid.0 + 46001928 --als-rv 0 0 \_ secure: kmk-master + +2. Print the blob contents for the kmk-master key:: + + $ keyctl print 46001928 + d9743445b640f3d59c1670dddc0bc9c2 + 34fc9aab7dd05c965e6120025012f029b + 07faa4776c4f6ed02899e35a135531e9a + 6e5c2b51132f9d5aef28f68738e658296 + 3fe583177cfe50d2542b659a13039 + + $ keyctl pipe 46001928 > secure_key.blob + +3. Load the blob in the user key ring:: + + $ keyctl load secure kmk-master "load 'cat secure_key.blob'" @u |