[PATCH 3/3] encrypted-keys: document new fscrypt key format
Signed-off-by: André Draszik Cc: Mimi Zohar Cc: David Howells Cc: James Morris Cc: "Serge E. Hallyn" Cc: "Theodore Y. Ts'o" Cc: Jaegeuk Kim Cc: Jonathan Corbet Cc: Kees Cook Cc: linux-integr...@vger.kernel.org Cc: keyri...@vger.kernel.org Cc: linux-security-mod...@vger.kernel.org Cc: linux-fscr...@vger.kernel.org Cc: linux-doc@vger.kernel.org --- 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 ..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 &
[PATCH v2 2/2] fscrypt: update documentation for encrypted key support
Signed-off-by: André Draszik Cc: "Theodore Y. Ts'o" Cc: Jaegeuk Kim Cc: Jonathan Corbet Cc: linux-fscr...@vger.kernel.org Cc: linux-ker...@vger.kernel.org Cc: Eric Biggers Cc: linux-doc@vger.kernel.org --- Documentation/filesystems/fscrypt.rst | 56 +++ 1 file changed, 51 insertions(+), 5 deletions(-) diff --git a/Documentation/filesystems/fscrypt.rst b/Documentation/filesystems/fscrypt.rst index 776ddc655f79..852ac2900b66 100644 --- a/Documentation/filesystems/fscrypt.rst +++ b/Documentation/filesystems/fscrypt.rst @@ -368,11 +368,19 @@ Adding keys To provide a master key, userspace must add it to an appropriate keyring using the add_key() system call (see: ``Documentation/security/keys/core.rst``). The key type must be -"logon"; keys of this type are kept in kernel memory and cannot be -read back by userspace. The key description must be "fscrypt:" -followed by the 16-character lower case hex representation of the -``master_key_descriptor`` that was set in the encryption policy. The -key payload must conform to the following structure:: +either "logon" or "encrypted"; "logon" keys are kept in kernel +memory and cannot be read back by userspace while "encrypted" +keys can be rooted in a "trusted" key and thus are protected by +a TPM and cannot be read by userspace in unencrypted form. Note +that while an "encrypted" key can also be rooted in a "user" key, +any "encrypted" key rooted in a "user" key can effectively be +retrieved in the clear, hence only rooting the key in a "trusted" +key has any useful security properties! + +The key description must be "fscrypt:" followed by the 16-character +lower case hex representation of the ``master_key_descriptor`` that +was set in the encryption policy. For a "logon" key, key payload +must conform to the following structure:: #define FS_MAX_KEY_SIZE 64 @@ -386,6 +394,17 @@ key payload must conform to the following structure:: ``raw`` with ``size`` indicating its size in bytes. That is, the bytes ``raw[0..size-1]`` (inclusive) are the actual key. +When using an "encrypted" key, only the actual ``raw`` key from above +fscrypt_key structure is needed:: + +keyctl add encrypted "fscrypt:``master_key_descriptor``" "new default trusted:``master-key-name`` ``size``" ``ring`` +keyctl add encrypted "fscrypt:``master_key_descriptor``" "load ``hex_blob``" ``ring`` + +Where:: + +master-key-name:= name of the trusted key this fscrypt master key + shall be rooted in + The key description prefix "fscrypt:" may alternatively be replaced with a filesystem-specific prefix such as "ext4:". However, the filesystem-specific prefixes are deprecated and should not be used in @@ -412,6 +431,33 @@ evicted. In the future there probably should be a way to provide keys directly to the filesystem instead, which would make the intended semantics clearer. +Complete Examples +-- + +Set fscrypt policy on an (empty) encrypted directory, /encrypted:: + +$ fscryptctl set_policy 1234567890123456 /encrypted + +Create an encrypted key "1234567890123456" of length 64 bytes with format +'fscrypt' and root it in a previously loaded trusted "kmk":: + +$ keyctl add encrypted "fscrypt:1234567890123456" "new default trusted:kmk 64" @u +839715473 + +$ keyctl print 839715473 +default trusted:kmk 64 e98a49dc11eb9312f46530879aac869300ee734035100f4ee +5441279369a4c9d83d6e59b8158d0a3de01790c0bb99af82e9603cb6977c7d1229338cda +80375aaf034678405a00c19806d6fb12490e39b1d7ca603c491b58a962345160e344ae51 +83483e066692d05f5ab3d8b9ea39cab0e + +$ keyctl pipe 839715473 > fscrypt.blob + +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 + Access semantics -- 2.15.1 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 3/3] encrypted-keys: document new fscrypt key format
Hi Eric, On Wed, 2018-01-10 at 20:48 -0800, Eric Biggers wrote: > Hi André, > > On Wed, Jan 10, 2018 at 12:44:18PM +0000, André Draszik wrote: > > diff --git a/Documentation/security/keys/fscrypt.rst > > b/Documentation/security/keys/fscrypt.rst > > new file mode 100644 > > index ..e4a29592513e > > --- /dev/null > > +++ b/Documentation/security/keys/fscrypt.rst > > @@ -0,0 +1,67 @@ > > + > > +Encrypted keys for the fscrypt subsystem > > + > > There is now documentation for fscrypt in > Documentation/filesystems/fscrypt.rst; > see in particular the "Adding keys" section. The documentation for any > new ways > to add keys should go in there. Done. > > > + > > +fscrypt allows file systems to implement transparent encryption and > > decryption > > +of files, similar to eCryptfs, using keys derived from a master key > > descriptor. > > Note that the master key *descriptor* refers to the hex string used in the > keyring key description. It is not the same as the master key itself, > which is > stored in the payload. The cryptography is done with the master key, not > with > the master key *descriptor*. Ups, thanks. > > [...] > > Please be very clear about exactly what security properties are achieved > by > using encrypted-keys. I've left out all of this in the updated documentation, as any such information should probably be in Documentation/security/keys/trusted- encrypted.rst in the first place. > [...] > > + > > +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 > > +c97986fc2e3326b5542e2b32216fc5007d9fd19cd3cb6668fa9850e954d2ba25e1b > > 8a331 > > +1b0c1f20666c > > + > > +$ keyctl pipe 1023935199 > fscrypt.blob > > What is the point of having the kernel wrap a key with the "user" key > type? It > seems pointless; userspace could just do it instead. Yes... My real reasoning is being able to use an encrypted key, backed by a trusted TPM key. I've updated the examples. > [...] > I think it's really only "trusted" wrapping keys where this new feature > would > have any useful security properties. So the documentation needs to > explain > that, and use that in the examples. You're right. Done. Cheers, André -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
Re: [PATCH 3/3] encrypted-keys: document new fscrypt key format
Thank you Ted, On Wed, 2018-01-17 at 13:05 -0500, Theodore Ts'o wrote: > On Wed, Jan 17, 2018 at 02:38:59PM +0000, André Draszik wrote: > > > > [...] > > > > > > Please be very clear about exactly what security properties are > > > achieved > > > by > > > using encrypted-keys. > > > > I've left out all of this in the updated documentation, as any such > > information should probably be in Documentation/security/keys/trusted- > > encrypted.rst in the first place. > > Where is this document going to be found / when will it be written? > It seems really odd to be requesting a do code review when the > specifications aren't available and/or haven't been written yet. I > prefer to review the *design* first, as opposed to trying to both > review the code and try to guess at the design and review my guess of > the design at the same time Does v3's commit message https://patchwork.kernel.org/patch/10173189/ serve as a good enough design document? Cheers, Andre' -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majord...@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html
