From patchwork Wed Jan 10 12:44:18 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: =?utf-8?q?Andr=C3=A9_Draszik?= X-Patchwork-Id: 10155081 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork.web.codeaurora.org (Postfix) with ESMTP id 9751D60231 for ; Wed, 10 Jan 2018 12:45:31 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 82D5328389 for ; Wed, 10 Jan 2018 12:45:31 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 7422C28397; Wed, 10 Jan 2018 12:45:31 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-6.9 required=2.0 tests=BAYES_00,RCVD_IN_DNSWL_HI autolearn=unavailable version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id E956428389 for ; Wed, 10 Jan 2018 12:45:30 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S932548AbeAJMpP (ORCPT ); Wed, 10 Jan 2018 07:45:15 -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 Received: by mail-wm0-f68.google.com with SMTP id g1so8764240wmg.2; Wed, 10 Jan 2018 04:44:23 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=tzbas+/2gLj+pQJi6KQsihcxe6rsxdFB9P8O192eSjI=; b=HScV8Gy5TyxUjZXV/+S/VjZB/p/WRiJyv8EfYsiHqoRTuA2fpeIvjcv9iSq/DgFmU1 XcfQ8+aQ52zIv9Hdd3ieiW3JW4c82JWE0hiaMrYDh3XKbLobdzFYN5ybEt7izXcIhL18 dlYunys0s0USTRqtD4uRkDo0Ok6J7JPeAF9PZ2sdw14pnB4+Q2i6I2Mzl7uaDMA2PpAO NK961uHXi66vAl4IdDtmMoCIPhkmPlzu730SIPY/4aoVUk0EFsfpafw82UC/mNCm2A7u G1KDsVLO9XC4kQvt1YR00IPSTbiFjOMUxJBUWXODKboX/e7GeGmePQDTc+0JuchKmcho iE7w== X-Gm-Message-State: AKGB3mIwpOjkBEIGm8sBLuwlfT9JGiuw4MFgeiIhB1ajNjhmHiEmEC/7 mFxuZ63CsryNXlrFC4YjOmBius49Ls4= X-Google-Smtp-Source: ACJfBouj4TWJpVn654D34dCxrPtbAEoDYh68HjbyFQfDRNPZBkYFP03zhyUudcRClH5QX1Mrr+SiVw== X-Received: by 10.80.179.131 with SMTP id s3mr26619293edd.289.1515588262377; Wed, 10 Jan 2018 04:44:22 -0800 (PST) Received: from tfsielt31850.garage.tyco.com ([77.107.218.170]) by smtp.gmail.com with ESMTPSA id c1sm1748119edk.72.2018.01.10.04.44.21 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Wed, 10 Jan 2018 04:44:21 -0800 (PST) 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 Sender: linux-fscrypt-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-fscrypt@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP 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``.