From mboxrd@z Thu Jan 1 00:00:00 1970 From: =?UTF-8?q?Andr=C3=A9=20Draszik?= Date: Wed, 10 Jan 2018 12:44:18 +0000 Subject: [PATCH 3/3] encrypted-keys: document new fscrypt key format Message-Id: <20180110124418.24385-3-git@andred.net> MIME-Version: 1.0 Content-Type: text/plain; charset="windows-1258" Content-Transfer-Encoding: base64 List-Id: References: <20180110124418.24385-1-git@andred.net> In-Reply-To: <20180110124418.24385-1-git@andred.net> To: linux-kernel@vger.kernel.org Cc: Mimi Zohar , David Howells , James Morris , "Serge E. Hallyn" , "Theodore Y. Ts'o" , Jaegeuk Kim , Jonathan Corbet , Kees Cook , linux-integrity@vger.kernel.org, keyrings@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-doc@vger.kernel.org U2lnbmVkLW9mZi1ieTogQW5kcsOpIERyYXN6aWsgPGdpdEBhbmRyZWQubmV0PgpDYzogTWltaSBa b2hhciA8em9oYXJAbGludXgudm5ldC5pYm0uY29tPgpDYzogRGF2aWQgSG93ZWxscyA8ZGhvd2Vs bHNAcmVkaGF0LmNvbT4KQ2M6IEphbWVzIE1vcnJpcyA8amFtZXMubC5tb3JyaXNAb3JhY2xlLmNv bT4KQ2M6ICJTZXJnZSBFLiBIYWxseW4iIDxzZXJnZUBoYWxseW4uY29tPgpDYzogIlRoZW9kb3Jl IFkuIFRzJ28iIDx0eXRzb0BtaXQuZWR1PgpDYzogSmFlZ2V1ayBLaW0gPGphZWdldWtAa2VybmVs Lm9yZz4KQ2M6IEpvbmF0aGFuIENvcmJldCA8Y29yYmV0QGx3bi5uZXQ+CkNjOiBLZWVzIENvb2sg PGtlZXNjb29rQGNocm9taXVtLm9yZz4KQ2M6IGxpbnV4LWludGVncml0eUB2Z2VyLmtlcm5lbC5v cmcKQ2M6IGtleXJpbmdzQHZnZXIua2VybmVsLm9yZwpDYzogbGludXgtc2VjdXJpdHktbW9kdWxl QHZnZXIua2VybmVsLm9yZwpDYzogbGludXgtZnNjcnlwdEB2Z2VyLmtlcm5lbC5vcmcKQ2M6IGxp bnV4LWRvY0B2Z2VyLmtlcm5lbC5vcmcKLS0tCiBEb2N1bWVudGF0aW9uL3NlY3VyaXR5L2tleXMv ZnNjcnlwdC5yc3QgICAgICAgICAgIHwgNjcgKysrKysrKysrKysrKysrKysrKysrKysKIERvY3Vt ZW50YXRpb24vc2VjdXJpdHkva2V5cy90cnVzdGVkLWVuY3J5cHRlZC5yc3QgfCAxMiArKy0tCiAy IGZpbGVzIGNoYW5nZWQsIDc0IGluc2VydGlvbnMoKyksIDUgZGVsZXRpb25zKC0pCiBjcmVhdGUg bW9kZSAxMDA2NDQgRG9jdW1lbnRhdGlvbi9zZWN1cml0eS9rZXlzL2ZzY3J5cHQucnN0CgpkaWZm IC0tZ2l0IGEvRG9jdW1lbnRhdGlvbi9zZWN1cml0eS9rZXlzL2ZzY3J5cHQucnN0IGIvRG9jdW1l bnRhdGlvbi9zZWN1cml0eS9rZXlzL2ZzY3J5cHQucnN0Cm5ldyBmaWxlIG1vZGUgMTAwNjQ0Cmlu ZGV4IDAwMDAwMDAwMDAwMC4uZTRhMjk1OTI1MTNlCi0tLSAvZGV2L251bGwKKysrIGIvRG9jdW1l bnRhdGlvbi9zZWN1cml0eS9rZXlzL2ZzY3J5cHQucnN0CkBAIC0wLDAgKzEsNjcgQEAKKz09PT09 PT09PT09PT09PT09PT09CitFbmNyeXB0ZWQga2V5cyBmb3IgdGhlIGZzY3J5cHQgc3Vic3lzdGVt Cis9PT09PT09PT09PT09PT09PT09PQorCitmc2NyeXB0IGFsbG93cyBmaWxlIHN5c3RlbXMgdG8g aW1wbGVtZW50IHRyYW5zcGFyZW50IGVuY3J5cHRpb24gYW5kIGRlY3J5cHRpb24KK29mIGZpbGVz LCBzaW1pbGFyIHRvIGVDcnlwdGZzLCB1c2luZyBrZXlzIGRlcml2ZWQgZnJvbSBhIG1hc3RlciBr ZXkgZGVzY3JpcHRvci4KKworVGhlIGRhdGEgc3RydWN0dXJlIGRlZmluZWQgYnkgZnNjcnlwdCB0 byBjb250YWluIGluZm9ybWF0aW9uIHJlcXVpcmVkIGZvciB0aGUKK21hc3RlciBrZXkgZGVzY3Jp cHRvciBpcyB0aGUgZnNjcnlwdF9rZXkgYW5kLCBjdXJyZW50bHksIGNhbiBiZSBzdG9yZWQgaW4g YQora2VybmVsIGtleSBvZiB0aGUgJ3VzZXInIHR5cGUsIGluc2VydGVkIGluIHRoZSB1c2VyJ3Mg c2Vzc2lvbiBzcGVjaWZpYyBrZXlyaW5nCitieSB0aGUgdXNlcnNwYWNlIHV0aWxpdGllcyAna2V5 Y3RsJywgJ2ZzY3J5cHRjdGwnLCBvciAnZTRjcnlwdCcuCisKK1RoZSAnZW5jcnlwdGVkJyBrZXkg dHlwZSBoYXMgYmVlbiBleHRlbmRlZCB3aXRoIHRoZSBpbnRyb2R1Y3Rpb24gb2YgdGhlIG5ldwor Zm9ybWF0ICdmc2NyeXB0JyBpbiBvcmRlciB0byBiZSB1c2VkIGluIGNvbmp1bmN0aW9uIHdpdGgg dGhlIGZzY3J5cHQKK3N1YnN5c3RlbS4gIEVuY3J5cHRlZCBrZXlzIG9mIHRoZSBuZXdseSBpbnRy b2R1Y2VkIGZvcm1hdCBzdG9yZSBhbgorZnNjcnlwdF9rZXkgaW4gaXRzIHBheWxvYWQgd2l0aCBh IG1hc3RlciBrZXkgZGVzY3JpcHRvciByYW5kb21seSBnZW5lcmF0ZWQgYnkKK3RoZSBrZXJuZWwg YW5kIHByb3RlY3RlZCBieSB0aGUgcGFyZW50IG1hc3RlciBrZXkuCisKK0luIG9yZGVyIHRvIGF2 b2lkIGtub3duLXBsYWludGV4dCBhdHRhY2tzLCB0aGUgZGF0YWJsb2Igb2J0YWluZWQgdGhyb3Vn aAorY29tbWFuZHMgJ2tleWN0bCBwcmludCcgb3IgJ2tleWN0bCBwaXBlJyBkb2VzIG5vdCBjb250 YWluIHRoZSBvdmVyYWxsCitmc2NyeXB0X2tleSwgdGhlIGNvbnRlbnRzIG9mIHdoaWNoIGlzIHdl bGwga25vd24sIGJ1dCBvbmx5IHRoZSBtYXN0ZXIga2V5CitkZXNjcmlwdG9yIGl0c2VsZiBpbiBl bmNyeXB0ZWQgZm9ybS4KKworVGhlIGZzY3J5cHQgc3Vic3lzdGVtIG1heSByZWFsbHkgYmVuZWZp dCBmcm9tIHVzaW5nIGVuY3J5cHRlZCBrZXlzIGluIHRoYXQgdGhlCityZXF1aXJlZCBrZXkgY2Fu IGJlIHNlY3VyZWx5IGdlbmVyYXRlZCBieSBhbiBBZG1pbmlzdHJhdG9yIGFuZCBwcm92aWRlZCBh dCBib290Cit0aW1lIGFmdGVyIHRoZSB1bnNlYWxpbmcgb2YgYSAndHJ1c3RlZCcga2V5IGluIG9y ZGVyIHRvIHBlcmZvcm0gdGhlIG1vdW50IGluIGEKK2NvbnRyb2xsZWQgZW52aXJvbm1lbnQuICBB bm90aGVyIGFkdmFudGFnZSBpcyB0aGF0IHRoZSBrZXkgaXMgbm90IGV4cG9zZWQgdG8KK3RocmVh dHMgb2YgbWFsaWNpb3VzIHNvZnR3YXJlLCBiZWNhdXNlIGl0IGlzIGF2YWlsYWJsZSBpbiBjbGVh ciBmb3JtIG9ubHkgYXQKK2tlcm5lbCBsZXZlbC4KKworVXNhZ2U6OgorCisgICBrZXljdGwgYWRk IGVuY3J5cHRlZCBmc2NyeXB0OnBvbGljeSAibmV3IGZzY3J5cHQga2V5LXR5cGU6bWFzdGVyLWtl eS1uYW1lIGtleWxlbiIgcmluZworICAga2V5Y3RsIGFkZCBlbmNyeXB0ZWQgZnNjcnlwdDpwb2xp Y3kgImxvYWQgaGV4X2Jsb2IiIHJpbmcKKyAgIGtleWN0bCB1cGRhdGUga2V5aWQgInVwZGF0ZSBr ZXktdHlwZTptYXN0ZXIta2V5LW5hbWUiCisKK1doZXJlOjoKKworCXBvbGljeTo9ICc8MTYgaGV4 YWRlY2ltYWwgY2hhcmFjdGVycz4nCisJa2V5LXR5cGU6PSAndHJ1c3RlZCcgfCAndXNlcicKKwlr ZXlsZW46PSAxNiB8IDMyIHwgNjQKKworCitFeGFtcGxlIG9mIGVuY3J5cHRlZCBrZXkgdXNhZ2Ug d2l0aCB0aGUgZnNjcnlwdCBzdWJzeXN0ZW06CisKK0NyZWF0ZSBhbiBlbmNyeXB0ZWQga2V5ICIx MjM0NTY3ODkwMTIzNDU2IiBvZiBsZW5ndGggNjQgYnl0ZXMgd2l0aCBmb3JtYXQKKydmc2NyeXB0 JyBhbmQgc2F2ZSBpdCB1c2luZyBhIHByZXZpb3VzbHkgbG9hZGVkIHVzZXIga2V5ICJ0ZXN0Ijo6 CisKKyAgICAkIGtleWN0bCBhZGQgZW5jcnlwdGVkIGZzY3J5cHQ6MTIzNDU2Nzg5MDEyMzQ1NiAi bmV3IGZzY3J5cHQgdXNlcjp0ZXN0IDY0IiBAdQorICAgIDEwMjM5MzUxOTkKKworICAgICQga2V5 Y3RsIHByaW50IDEwMjM5MzUxOTkKKyAgICBmc2NyeXB0IHVzZXI6dGVzdCA2NCBlNTYwNjY4OWZk YzI1ZDc4YTc4NzI0OWY0MDY5ZmIzYjAwN2U5OTJmNGIyMWQwZWRhNjAKKyAgICBjOTc5ODZmYzJl MzMyNmI1NTQyZTJiMzIyMTZmYzUwMDdkOWZkMTljZDNjYjY2NjhmYTk4NTBlOTU0ZDJiYTI1ZTFi OGEzMzEKKyAgICAxYjBjMWYyMDY2NmMKKworICAgICQga2V5Y3RsIHBpcGUgMTAyMzkzNTE5OSA+ IGZzY3J5cHQuYmxvYgorCitTZXQgZnNjcnlwdCBwb2xpY3kgb24gYW4gKGVtcHR5KSBlbmNyeXB0 ZWQgZGlyZWN0b3J5IC9lbmNyeXB0ZWQ6OgorCisgICAgJCBmc2NyeXB0Y3RsIHNldF9wb2xpY3kg MTIzNDU2Nzg5MDEyMzQ1NiAvZW5jcnlwdGVkCisKK1RoZSBkaXJlY3RvcnkgcG9saWN5IHdpbGwg cmVtYWluIGFjcm9zcyByZWJvb3RzLCBzbyBhZnRlciBhIHJlYm9vdCB0aGUga2V5CitnZW5lcmF0 ZWQgZWFybGllciB3aWxsIHNpbXBseSBoYXZlIHRvIGJlIGxvYWRlZCBpbnRvIHRoZSBrZXJuZWwg a2V5cmluZworYWdhaW46OgorCisgICAgJCBrZXljdGwgYWRkIGVuY3J5cHRlZCBmc2NyeXB0OjEy MzQ1Njc4OTAxMjM0NTYgImxvYWQgJChjYXQgZnNjcnlwdC5ibG9iKSIgQHUKZGlmZiAtLWdpdCBh L0RvY3VtZW50YXRpb24vc2VjdXJpdHkva2V5cy90cnVzdGVkLWVuY3J5cHRlZC5yc3QgYi9Eb2N1 bWVudGF0aW9uL3NlY3VyaXR5L2tleXMvdHJ1c3RlZC1lbmNyeXB0ZWQucnN0CmluZGV4IDNiYjI0 ZTA5YTMzMi4uZDAyNTAxMTJiYjRkIDEwMDY0NAotLS0gYS9Eb2N1bWVudGF0aW9uL3NlY3VyaXR5 L2tleXMvdHJ1c3RlZC1lbmNyeXB0ZWQucnN0CisrKyBiL0RvY3VtZW50YXRpb24vc2VjdXJpdHkv a2V5cy90cnVzdGVkLWVuY3J5cHRlZC5yc3QKQEAgLTc2LDcgKzc2LDcgQEAgVXNhZ2U6OgogCiBX aGVyZTo6CiAKLQlmb3JtYXQ6PSAnZGVmYXVsdCB8IGVjcnlwdGZzJworCWZvcm1hdDo9ICdkZWZh dWx0IHwgZWNyeXB0ZnMgfCBmc2NyeXB0JwogCWtleS10eXBlOj0gJ3RydXN0ZWQnIHwgJ3VzZXIn CiAKIApAQCAtMTY5LDcgKzE2OSw5IEBAIExvYWQgYW4gZW5jcnlwdGVkIGtleSAiZXZtIiBmcm9t IHNhdmVkIGJsb2I6OgogICAgIDI0NzE3YzY0IDU5NzJkY2I4MmFiMmRkZTgzMzc2ZDgyYjJlM2Mw OWZmYwogCiBPdGhlciB1c2VzIGZvciB0cnVzdGVkIGFuZCBlbmNyeXB0ZWQga2V5cywgc3VjaCBh cyBmb3IgZGlzayBhbmQgZmlsZSBlbmNyeXB0aW9uCi1hcmUgYW50aWNpcGF0ZWQuICBJbiBwYXJ0 aWN1bGFyIHRoZSBuZXcgZm9ybWF0ICdlY3J5cHRmcycgaGFzIGJlZW4gZGVmaW5lZCBpbgotaW4g b3JkZXIgdG8gdXNlIGVuY3J5cHRlZCBrZXlzIHRvIG1vdW50IGFuIGVDcnlwdGZzIGZpbGVzeXN0 ZW0uICBNb3JlIGRldGFpbHMKLWFib3V0IHRoZSB1c2FnZSBjYW4gYmUgZm91bmQgaW4gdGhlIGZp bGUKLWBgRG9jdW1lbnRhdGlvbi9zZWN1cml0eS9rZXlzL2VjcnlwdGZzLnJzdGBgLgorYXJlIGFu dGljaXBhdGVkLiAgSW4gcGFydGljdWxhciB0aGUgbmV3IGZvcm1hdHMgJ2VjcnlwdGZzJyBhbmQg J2ZzY3J5cHQnIGhhdmUKK2JlZW4gZGVmaW5lZCBpbiBvcmRlciB0byB1c2UgZW5jcnlwdGVkIGtl eXMgdG8gbW91bnQgYW4gZUNyeXB0ZnMgb3IgZnNjcnlwdAorZmlsZXN5c3RlbSwgcmVzcGVjdGl2 ZWx5LiBNb3JlIGRldGFpbHMgYWJvdXQgdGhlIHVzYWdlIGNhbiBiZSBmb3VuZCBpbiB0aGUKK2Zp bGVzCitgYERvY3VtZW50YXRpb24vc2VjdXJpdHkva2V5cy9lY3J5cHRmcy5yc3RgYCBhbmQKK2Bg RG9jdW1lbnRhdGlvbi9zZWN1cml0eS9rZXlzL2ZzY3J5cHQucnN0YGAuCi0tIAoyLjE1LjEKCi0t ClRvIHVuc3Vic2NyaWJlIGZyb20gdGhpcyBsaXN0OiBzZW5kIHRoZSBsaW5lICJ1bnN1YnNjcmli ZSBrZXlyaW5ncyIgaW4KdGhlIGJvZHkgb2YgYSBtZXNzYWdlIHRvIG1ham9yZG9tb0B2Z2VyLmtl cm5lbC5vcmcKTW9yZSBtYWpvcmRvbW8gaW5mbyBhdCAgaHR0cDovL3ZnZXIua2VybmVsLm9yZy9t YWpvcmRvbW8taW5mby5odG1s From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm0-f68.google.com ([74.125.82.68]:44023 "EHLO mail-wm0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933510AbeAJMoY (ORCPT ); Wed, 10 Jan 2018 07:44:24 -0500 From: =?UTF-8?q?Andr=C3=A9=20Draszik?= Subject: [PATCH 3/3] encrypted-keys: document new fscrypt key format Date: Wed, 10 Jan 2018 12:44:18 +0000 Message-Id: <20180110124418.24385-3-git@andred.net> In-Reply-To: <20180110124418.24385-1-git@andred.net> References: <20180110124418.24385-1-git@andred.net> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sender: linux-fscrypt-owner@vger.kernel.org To: linux-kernel@vger.kernel.org Cc: Mimi Zohar , David Howells , James Morris , "Serge E. Hallyn" , "Theodore Y. Ts'o" , Jaegeuk Kim , Jonathan Corbet , Kees Cook , linux-integrity@vger.kernel.org, keyrings@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-doc@vger.kernel.org List-ID: 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-integrity@vger.kernel.org Cc: keyrings@vger.kernel.org Cc: linux-security-module@vger.kernel.org Cc: linux-fscrypt@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 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 From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mail-wm0-f68.google.com ([74.125.82.68]:44023 "EHLO mail-wm0-f68.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S933510AbeAJMoY (ORCPT ); Wed, 10 Jan 2018 07:44:24 -0500 From: =?UTF-8?q?Andr=C3=A9=20Draszik?= To: linux-kernel@vger.kernel.org Cc: Mimi Zohar , David Howells , James Morris , "Serge E. Hallyn" , "Theodore Y. Ts'o" , Jaegeuk Kim , Jonathan Corbet , Kees Cook , linux-integrity@vger.kernel.org, keyrings@vger.kernel.org, linux-security-module@vger.kernel.org, linux-fscrypt@vger.kernel.org, linux-doc@vger.kernel.org Subject: [PATCH 3/3] encrypted-keys: document new fscrypt key format Date: Wed, 10 Jan 2018 12:44:18 +0000 Message-Id: <20180110124418.24385-3-git@andred.net> In-Reply-To: <20180110124418.24385-1-git@andred.net> References: <20180110124418.24385-1-git@andred.net> MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Sender: linux-integrity-owner@vger.kernel.org List-ID: Signed-off-by: Andre 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-integrity@vger.kernel.org Cc: keyrings@vger.kernel.org Cc: linux-security-module@vger.kernel.org Cc: linux-fscrypt@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 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 From mboxrd@z Thu Jan 1 00:00:00 1970 From: git@andred.net (=?UTF-8?q?Andr=C3=A9=20Draszik?=) Date: Wed, 10 Jan 2018 12:44:18 +0000 Subject: [PATCH 3/3] encrypted-keys: document new fscrypt key format In-Reply-To: <20180110124418.24385-1-git@andred.net> References: <20180110124418.24385-1-git@andred.net> Message-ID: <20180110124418.24385-3-git@andred.net> To: linux-security-module@vger.kernel.org List-Id: linux-security-module.vger.kernel.org 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-integrity at vger.kernel.org Cc: keyrings at vger.kernel.org Cc: linux-security-module at vger.kernel.org Cc: linux-fscrypt at vger.kernel.org Cc: linux-doc at 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 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 -- To unsubscribe from this list: send the line "unsubscribe linux-security-module" in the body of a message to majordomo at vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html