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 000000000000..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. > + > +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*. > +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. Please be very clear about exactly what security properties are achieved by using encrypted-keys. Note that such keys are present in the clear in kernel memory, so they will be exposed by any exploit that compromises the kernel, or even just finds a way to read its memory. (And if you've been paying attention in the last week, you may be aware that certain CPU vendors have "helpfully" made reading kernel memory quite easy.) So, it's definitely *not* categorically true that "the key is not exposed to threats of malicious software". Also note that fscrypt is already using the "logon" key type which cannot be read by userspace (without exploits). This is different from eCryptfs which uses the "user" key type. > +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 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. Note that if you use keyctl_read() to read from an encrypted-key, you can actually request that the key be encrypted using an arbitrary key of the type with which the key is supposed to be wrapped. This can be done by adding a key to your thread/process/session keyring whose type and description matches the intended wrapping key. Thus, any "encrypted" key wrapped with a "user" key can effectively be retrieved in the clear by calling keyctl_read(), then decrypting the ciphertext in userspace. Perhaps that's actually a bug; I don't know. But using "user" wrapping keys seems pretty pointless anyway. 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. Eric -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
