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
