[PATCH 3/3] encrypted-keys: document new fscrypt key format

[Andrà Draszik]

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