fscrypt uses a master key for each directory policy from which all further keys for that policy are derived, and at the moment such a master key has to be inserted into a kernel keyring as a 'logon' key by user-space. While 'logon' keys have the nice property of not being readable by user-space (keyctl dump etc.), the fscrypt master key still needs to be generated initially, in a secure way, and it needs to be saved somewhere for subsequent reboots, and hence also needs securing itself. Usage of the 'logon' key means that it is up to user-space to do all that, opening up the possibility of creating cryptographically non-sound master keys, or not storing the master key securely across reboots. One approach for securing the master key would be to do that using a TPM and while one could manually do so e.g. using tpm-tools, that still leaves creation and actual correct usage of tpm-tools up to user-space, though. As an aside, tpm-tools needs the tcsd daemon running, which makes it awkward to use from within an initramfs, and while other libraries for interfacing with a TPM do exist, there appears to be a better way: The kernel already has a concept of trusted as well as encrypted keys. Trusted keys are TPM backed keys, which can be sealed to PCRs and also easily be re-sealed against new future PCRs, and encrypted keys are keys that are encrypted using another key, e.g. a trusted key. All are generated automatically by the kernel using the RNG and never leave kernel memory space (bar any kernel or hardware bugs). So it seems reasonable to allow the fscrypt subsystem to work with encrypted keys as well. This is what this change here does. We can utilise keys that never ever exist in user-space, not even at initial creation time, as well as simplifying usage / configuration. Something very very similar exists for eCrypts already. With these patches, we can kmk_id=$(keyctl add trusted kmk "new 128 [pcrinfo=...]" @u) fscrypt_id=$(keyctl add encrypted fscrypt:1234567890123456 "new default trusted:kmk 64" @u) fscryptctl set_policy 1234567890123456 /encrypted then we can save those keys for after reboot (optionally TPM-sealed as per the pcrinfo= argument above): keyctl pipe ${kmk_id} > /keys/kmk.blob keyctl pipe ${fscrypt_id} > /keys/fscrypt.blob and on subsequent boots we can simply insert them again (optionally benefitting from the TPM's capability to only unseal kmk.blob when the system is in the expected state, thereby also protecting fscrypt.blob): keyctl add trusted kmk "load $(cat /keys/kmk.blob)" @u keyctl add encrypted fscrypt:1234567890123456 "load $(cat /keys/fscrypt.blob)" @u 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: Kees Cook <keescook@xxxxxxxxxxxx> Cc: Eric Biggers <ebiggers@xxxxxxxxxx> Cc: linux-integrity@xxxxxxxxxxxxxxx Cc: keyrings@xxxxxxxxxxxxxxx Cc: linux-security-module@xxxxxxxxxxxxxxx Cc: linux-fscrypt@xxxxxxxxxxxxxxx Cc: linux-kernel@xxxxxxxxxxxxxxx --- changes in v3: * merge documentation changes into this commit * update derive_key_aes() signature to not take a struct fscrypt_key and update all callers * try to use the 'encrypted' key as fallback only if the a 'logon' key isn't present (ENOKEY) * update fscrypt_get_encrypted_key() to take a 'description', not a 'sig' * update commit message * re-add keyrings mailing list and encrypted-keys maintainers to Cc changes in v2: * dropped the previously added 'fscrypt' encrypted-key, and just use the 'default' format --- Documentation/filesystems/fscrypt.rst | 56 +++++++++++++++++++-- fs/crypto/keyinfo.c | 92 ++++++++++++++++++++++------------- 2 files changed, 110 insertions(+), 38 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 ================ diff --git a/fs/crypto/keyinfo.c b/fs/crypto/keyinfo.c index 5e6e846f5a24..3d20addadcd4 100644 --- a/fs/crypto/keyinfo.c +++ b/fs/crypto/keyinfo.c @@ -10,6 +10,7 @@ */ #include <keys/user-type.h> +#include <keys/encrypted-type.h> #include <linux/scatterlist.h> #include <linux/ratelimit.h> #include <crypto/aes.h> @@ -20,14 +21,16 @@ static struct crypto_shash *essiv_hash_tfm; /** * derive_key_aes() - Derive a key using AES-128-ECB - * @deriving_key: Encryption key used for derivation. - * @source_key: Source key to which to apply derivation. - * @derived_raw_key: Derived raw key. + * @deriving_key: Encryption key used for derivation. + * @source_key: Raw source key to which to apply derivation. + * @source_key_len: Length of the source key. + * @derived_raw_key: Derived raw key. * * Return: Zero on success; non-zero otherwise. */ static int derive_key_aes(u8 deriving_key[FS_AES_128_ECB_KEY_SIZE], - const struct fscrypt_key *source_key, + const u8 source_key[FS_MAX_KEY_SIZE], + u32 source_key_len, u8 derived_raw_key[FS_MAX_KEY_SIZE]) { int res = 0; @@ -55,9 +58,9 @@ static int derive_key_aes(u8 deriving_key[FS_AES_128_ECB_KEY_SIZE], if (res < 0) goto out; - sg_init_one(&src_sg, source_key->raw, source_key->size); - sg_init_one(&dst_sg, derived_raw_key, source_key->size); - skcipher_request_set_crypt(req, &src_sg, &dst_sg, source_key->size, + sg_init_one(&src_sg, source_key, source_key_len); + sg_init_one(&dst_sg, derived_raw_key, source_key_len); + skcipher_request_set_crypt(req, &src_sg, &dst_sg, source_key_len, NULL); res = crypto_wait_req(crypto_skcipher_encrypt(req), &wait); out: @@ -66,14 +69,21 @@ static int derive_key_aes(u8 deriving_key[FS_AES_128_ECB_KEY_SIZE], return res; } -static int validate_user_key(struct fscrypt_info *crypt_info, +static inline struct key *fscrypt_get_encrypted_key(const char *description) +{ + if (IS_ENABLED(CONFIG_ENCRYPTED_KEYS)) + return request_key(&key_type_encrypted, description, NULL); + return ERR_PTR(-ENOKEY); +} + +static int validate_keyring_key(struct fscrypt_info *crypt_info, struct fscrypt_context *ctx, u8 *raw_key, const char *prefix, int min_keysize) { char *description; struct key *keyring_key; - struct fscrypt_key *master_key; - const struct user_key_payload *ukp; + const u8 *master_key; + u32 master_key_len; int res; description = kasprintf(GFP_NOFS, "%s%*phN", prefix, @@ -83,39 +93,55 @@ static int validate_user_key(struct fscrypt_info *crypt_info, return -ENOMEM; keyring_key = request_key(&key_type_logon, description, NULL); + if (keyring_key == ERR_PTR(-ENOKEY)) + keyring_key = fscrypt_get_encrypted_key(description); kfree(description); if (IS_ERR(keyring_key)) return PTR_ERR(keyring_key); down_read(&keyring_key->sem); - if (keyring_key->type != &key_type_logon) { + if (keyring_key->type == &key_type_logon) { + const struct user_key_payload *ukp; + const struct fscrypt_key *fk; + + ukp = user_key_payload_locked(keyring_key); + if (!ukp) { + /* key was revoked before we acquired its semaphore */ + res = -EKEYREVOKED; + goto out; + } + if (ukp->datalen != sizeof(struct fscrypt_key)) { + res = -EINVAL; + goto out; + } + fk = (struct fscrypt_key *)ukp->data; + master_key = fk->raw; + master_key_len = fk->size; + } else if (keyring_key->type == &key_type_encrypted) { + const struct encrypted_key_payload *ekp; + + ekp = keyring_key->payload.data[0]; + master_key = ekp->decrypted_data; + master_key_len = ekp->decrypted_datalen; + } else { printk_once(KERN_WARNING - "%s: key type must be logon\n", __func__); + "%s: key type must be logon or encrypted\n", + __func__); res = -ENOKEY; goto out; } - ukp = user_key_payload_locked(keyring_key); - if (!ukp) { - /* key was revoked before we acquired its semaphore */ - res = -EKEYREVOKED; - goto out; - } - if (ukp->datalen != sizeof(struct fscrypt_key)) { - res = -EINVAL; - goto out; - } - master_key = (struct fscrypt_key *)ukp->data; BUILD_BUG_ON(FS_AES_128_ECB_KEY_SIZE != FS_KEY_DERIVATION_NONCE_SIZE); - if (master_key->size < min_keysize || master_key->size > FS_MAX_KEY_SIZE - || master_key->size % AES_BLOCK_SIZE != 0) { + if (master_key_len < min_keysize || master_key_len > FS_MAX_KEY_SIZE + || master_key_len % AES_BLOCK_SIZE != 0) { printk_once(KERN_WARNING - "%s: key size incorrect: %d\n", - __func__, master_key->size); + "%s: key size incorrect: %u\n", + __func__, master_key_len); res = -ENOKEY; goto out; } - res = derive_key_aes(ctx->nonce, master_key, raw_key); + res = derive_key_aes(ctx->nonce, master_key, master_key_len, raw_key); + out: up_read(&keyring_key->sem); key_put(keyring_key); @@ -302,12 +328,12 @@ int fscrypt_get_encryption_info(struct inode *inode) if (!raw_key) goto out; - res = validate_user_key(crypt_info, &ctx, raw_key, FS_KEY_DESC_PREFIX, - keysize); + res = validate_keyring_key(crypt_info, &ctx, raw_key, + FS_KEY_DESC_PREFIX, keysize); if (res && inode->i_sb->s_cop->key_prefix) { - int res2 = validate_user_key(crypt_info, &ctx, raw_key, - inode->i_sb->s_cop->key_prefix, - keysize); + int res2 = validate_keyring_key(crypt_info, &ctx, raw_key, + inode->i_sb->s_cop->key_prefix, + keysize); if (res2) { if (res2 == -ENOKEY) res = -ENOKEY; -- 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
![]() |