Signed-off-by: André Draszik <git@xxxxxxxxxx> Cc: Mimi Zohar <zohar@xxxxxxxxxxxxxxxxxx> Cc: David Howells <dhowells@xxxxxxxxxx> Cc: James Morris <james.l.morris@xxxxxxxxxx> Cc: "Serge E. Hallyn" <serge@xxxxxxxxxx> Cc: "Theodore Y. Ts'o" <tytso@xxxxxxx> Cc: Jaegeuk Kim <jaegeuk@xxxxxxxxxx> Cc: Jonathan Corbet <corbet@xxxxxxx> Cc: Kees Cook <keescook@xxxxxxxxxxxx> Cc: linux-integrity@xxxxxxxxxxxxxxx Cc: keyrings@xxxxxxxxxxxxxxx Cc: linux-security-module@xxxxxxxxxxxxxxx Cc: linux-fscrypt@xxxxxxxxxxxxxxx Cc: linux-doc@xxxxxxxxxxxxxxx --- Documentation/security/keys/fscrypt.rst | 67 +++++++++++++++++++++++ Documentation/security/keys/trusted-encrypted.rst | 12 ++-- 2 files changed, 74 insertions(+), 5 deletions(-) create mode 100644 Documentation/security/keys/fscrypt.rst diff --git a/Documentation/security/keys/fscrypt.rst b/Documentation/security/keys/fscrypt.rst new file mode 100644 index 000000000000..e4a29592513e --- /dev/null +++ b/Documentation/security/keys/fscrypt.rst @@ -0,0 +1,67 @@ +======================================== +Encrypted keys for the fscrypt subsystem +======================================== + +fscrypt allows file systems to implement transparent encryption and decryption +of files, similar to eCryptfs, using keys derived from a master key descriptor. + +The data structure defined by fscrypt to contain information required for the +master key descriptor is the fscrypt_key and, currently, can be stored in a +kernel key of the 'user' type, inserted in the user's session specific keyring +by the userspace utilities 'keyctl', 'fscryptctl', or 'e4crypt'. + +The 'encrypted' key type has been extended with the introduction of the new +format 'fscrypt' in order to be used in conjunction with the fscrypt +subsystem. Encrypted keys of the newly introduced format store an +fscrypt_key in its payload with a master key descriptor randomly generated by +the kernel and protected by the parent master key. + +In order to avoid known-plaintext attacks, the datablob obtained through +commands 'keyctl print' or 'keyctl pipe' does not contain the overall +fscrypt_key, the contents of which is well known, but only the master key +descriptor itself in encrypted form. + +The fscrypt subsystem may really benefit from using encrypted keys in that the +required key can be securely generated by an Administrator and provided at boot +time after the unsealing of a 'trusted' key in order to perform the mount in a +controlled environment. Another advantage is that the key is not exposed to +threats of malicious software, because it is available in clear form only at +kernel level. + +Usage:: + + keyctl add encrypted fscrypt:policy "new fscrypt key-type:master-key-name keylen" ring + keyctl add encrypted fscrypt:policy "load hex_blob" ring + keyctl update keyid "update key-type:master-key-name" + +Where:: + + policy:= '<16 hexadecimal characters>' + key-type:= 'trusted' | 'user' + keylen:= 16 | 32 | 64 + + +Example of encrypted key usage with the fscrypt subsystem: + +Create an encrypted key "1234567890123456" of length 64 bytes with format +'fscrypt' and save it using a previously loaded user key "test":: + + $ keyctl add encrypted fscrypt:1234567890123456 "new fscrypt user:test 64" @u + 1023935199 + + $ keyctl print 1023935199 + fscrypt user:test 64 e5606689fdc25d78a787249f4069fb3b007e992f4b21d0eda60 + c97986fc2e3326b5542e2b32216fc5007d9fd19cd3cb6668fa9850e954d2ba25e1b8a331 + 1b0c1f20666c + + $ keyctl pipe 1023935199 > fscrypt.blob + +Set fscrypt policy on an (empty) encrypted directory /encrypted:: + + $ fscryptctl set_policy 1234567890123456 /encrypted + +The directory policy will remain across reboots, so after a reboot the key +generated earlier will simply have to be loaded into the kernel keyring +again:: + + $ keyctl add encrypted fscrypt:1234567890123456 "load $(cat fscrypt.blob)" @u diff --git a/Documentation/security/keys/trusted-encrypted.rst b/Documentation/security/keys/trusted-encrypted.rst index 3bb24e09a332..d0250112bb4d 100644 --- a/Documentation/security/keys/trusted-encrypted.rst +++ b/Documentation/security/keys/trusted-encrypted.rst @@ -76,7 +76,7 @@ Usage:: Where:: - format:= 'default | ecryptfs' + format:= 'default | ecryptfs | fscrypt' key-type:= 'trusted' | 'user' @@ -169,7 +169,9 @@ Load an encrypted key "evm" from saved blob:: 24717c64 5972dcb82ab2dde83376d82b2e3c09ffc Other uses for trusted and encrypted keys, such as for disk and file encryption -are anticipated. In particular the new format 'ecryptfs' has been defined in -in order to use encrypted keys to mount an eCryptfs filesystem. More details -about the usage can be found in the file -``Documentation/security/keys/ecryptfs.rst``. +are anticipated. In particular the new formats 'ecryptfs' and 'fscrypt' have +been defined in order to use encrypted keys to mount an eCryptfs or fscrypt +filesystem, respectively. More details about the usage can be found in the +files +``Documentation/security/keys/ecryptfs.rst`` and +``Documentation/security/keys/fscrypt.rst``. -- 2.15.1 -- To unsubscribe from this list: send the line "unsubscribe linux-fscrypt" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
![]() |