Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S934465AbeAJMpQ (ORCPT + 1 other); Wed, 10 Jan 2018 07:45:16 -0500 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 X-Google-Smtp-Source: ACJfBouj4TWJpVn654D34dCxrPtbAEoDYh68HjbyFQfDRNPZBkYFP03zhyUudcRClH5QX1Mrr+SiVw== 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> X-Mailer: git-send-email 2.15.1 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-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Return-Path: 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