From patchwork Fri Dec 14 21:10:08 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Jiang X-Patchwork-Id: 10731679 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 5CB4E14E2 for ; Fri, 14 Dec 2018 21:10:11 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id CDD512D8BA for ; Fri, 14 Dec 2018 21:10:10 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id C25D82D8C0; Fri, 14 Dec 2018 21:10:10 +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=-2.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from ml01.01.org (ml01.01.org [198.145.21.10]) (using TLSv1.2 with cipher DHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.wl.linuxfoundation.org (Postfix) with ESMTPS id 131CF2D8BA for ; Fri, 14 Dec 2018 21:10:10 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 09F69211A45BD; Fri, 14 Dec 2018 13:10:10 -0800 (PST) X-Original-To: linux-nvdimm@lists.01.org Delivered-To: linux-nvdimm@lists.01.org Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=134.134.136.20; helo=mga02.intel.com; envelope-from=dave.jiang@intel.com; receiver=linux-nvdimm@lists.01.org Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 2DFFF211A4593 for ; Fri, 14 Dec 2018 13:10:09 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga006.jf.intel.com ([10.7.209.51]) by orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 14 Dec 2018 13:10:09 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,354,1539673200"; d="scan'208";a="100792332" Received: from djiang5-desk3.ch.intel.com ([143.182.136.93]) by orsmga006.jf.intel.com with ESMTP; 14 Dec 2018 13:10:08 -0800 Subject: [PATCH v6 12/12] ndctl: documentation for security and key management From: Dave Jiang To: "vishal.l.verma."@intel.com, dan.j.williams@intel.com Date: Fri, 14 Dec 2018 14:10:08 -0700 Message-ID: <154482180840.65434.1342856065971626396.stgit@djiang5-desk3.ch.intel.com> In-Reply-To: <154482154540.65434.14399161818571651882.stgit@djiang5-desk3.ch.intel.com> References: <154482154540.65434.14399161818571651882.stgit@djiang5-desk3.ch.intel.com> User-Agent: StGit/unknown-version MIME-Version: 1.0 X-BeenThere: linux-nvdimm@lists.01.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "Linux-nvdimm developer list." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: linux-nvdimm@lists.01.org Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" X-Virus-Scanned: ClamAV using ClamSMTP Adding the theory of operation for Intel DSM operations. Signed-off-by: Dave Jiang --- Documentation/ndctl/intel-nvdimm-security.txt | 139 ++++++++++++++++++++++ Documentation/ndctl/ndctl-disable-passphrase.txt | 2 Documentation/ndctl/ndctl-enable-passphrase.txt | 4 + Documentation/ndctl/ndctl-freeze-security.txt | 2 Documentation/ndctl/ndctl-sanitize-dimm.txt | 2 Documentation/ndctl/ndctl-update-passphrase.txt | 2 6 files changed, 151 insertions(+) create mode 100644 Documentation/ndctl/intel-nvdimm-security.txt diff --git a/Documentation/ndctl/intel-nvdimm-security.txt b/Documentation/ndctl/intel-nvdimm-security.txt new file mode 100644 index 00000000..0c9a41a4 --- /dev/null +++ b/Documentation/ndctl/intel-nvdimm-security.txt @@ -0,0 +1,139 @@ +// SPDX-License-Identifier: GPL-2.0 + +THEORY OF OPERATOIN +------------------- +With the introduction of Intel Device Specific Methods (DSM) specification +v1.7 and v1.8 [1], security DSMs were introduced. Ndctl supports enable +passhprase, update passphrase, disable security, freeze security, secure +(crypto) erase, overwrite, master passphrase enable, master passphrase update, +and master passphrase secure (crypto) erase. The DSM that is not supported by +ndctl is the unlock DSM, which is left to the kernel to manage. + +The security management for nvdimm is composed of two parts. The front end +utilizes the Linux key management framework (trusted and encrypted keys [2]). +It uses the keyutils on the user side and Linux key management APIs in +the kernel. The backend takes the decrypted payload of the key and passes the +plaintext payload to the nvdimm for processing. + +Unlike typical DSMs, the security DSMs are managed through the 'security' +sysfs attribute under the dimm devices rather than an ioctl call by libndctl. +The relevant key id is written to the 'security' attribute and the kernel will +pull that key from the kernel user key ring for processing. + +The entire security process starts with a master key that is used to seal the +encrypted keys that are used to protect the passphrase for each nvdimm. We +recommend using THE system master trusted key from the Trusted Platform +Module (TPM). However, a trusted master key generated by the TPM can also +be used. And for testing purposes, a user key with randomized payload can +also be served as a master key. See [2] for details. To perform any security +operations, it is expected that at the minimal the master key is already +in the kernel user keyring as shown in example below: + +> keyctl show +Session Keyring + 736023423 --alswrv 0 0 keyring: _ses + 675104189 --alswrv 0 65534 \_ keyring: _uid.0 + 680187394 --alswrv 0 0 \_ trusted: nvdimm-master + +All operations expect the relevant regions associated to the nvdimm are +disabled before proceeding, except overwrite. Overwrite expects the +relevant nvdimm also be disabled. + +The follow on sections describe specifics of each security features. + +UNLOCK +------ +Unlock is performed by the kernel, however a preparation step must happen +before the unlock DSM can be issued by the kernel. The expectation is that +during initramfs, a setup script is called before the libnvdimm module is +loaded by modprobe. The said script will inject the master key and the +related encrypted keys into the kernel user key ring. A reference modprobe +config file and a setup script have been provided by ndctl. When the +nvdimm driver probes, it will +1. First, Check the security state of the device and see if the dimm is locked +2. Request the associated encrypted key from the kernel user key ring. +3. Finally, create the unlock DSM and copy the decrypted payload into the DSM + passphrase field, and issue the DSM to unlock the DIMM. + +If the DIMM is already unlocked, the kernel will attempt to revalidate the key. +This can be overriden with a kernel module parameter. If we fail to revalidate +the key, the kernel will freeze the security and disallow any further security +configuration changes. + +ENABLE USER PASSPHRASE +---------------------- +To enable the user passphrase for a DIMM, it is expected that the master key +is already in the kernel user key ring and the master key name is passed to +ndctl so it can do key management. An encrypted key with a 32byte payload +and encrypted key format 'enc32' is created and sealed by the master key. Be +aware that the passphrase is never provided by or visible to the user. +The decrypted payload for the encrypted key will be randomly generated by the +kernel and userspace does not have access to this decrypted payload. When the +encrypted key is created, a binary blob of the encrypted key is written to the +designated key blob storage directory (/etc/ndctl/keys as default). The user is +responsible for backing up the dimm key blobs to a secure location. When a key +is successfully loaded into the kernel user key ring, the payload is decrypted +and can be accessed by the kernel. + +Key ids are written to the 'security' sysfs attribute with the command "update". +A key id of 0 is provided for the old key id. The kernel will see that the +update call is an enable call because the 0 old key id. A "passphrase update" +DSM is issued by the kernel with the old passphrase as 0s. + +UPDATE USER PASSPHRASE +---------------------- +The update user passphrase operation uses the same DSM command as enable user +passphrase. Most of the work is done on the key management. The user will +provide a new master key name for the new passphrase key or use the existing +one. Ndctl will use whatever master key name that is passed in. The following +operation is performed for update: +1. Remove the associated encrypted key from the kernel user key ring. +2. Rename the key blob to old. +3. Load the now old key blob into kernel user key ring with "old" name. +4. Create new encrypted key and seal with master key. +5. Generate new key blob. +6. Send DSM with old and new passphrase via the decrypted key payloads. +7. On success, remove old key from key ring and old key blob. + +DISABLE USER PASSPHRASE +----------------------- +Ndctl will look up the key id for the current associated key and write to sysfs. +Upon success of disabling, the key will be removed from the kernel user key +ring and the related key blob will also be deleted. + +CRYPTO (SECURE) ERASE +--------------------- +This operation is similar to disable the passphrase. The kernel will issue +wbinvd before and after the operation to ensure no data corruption from stale +CPU cache. The "sanitize-dimm" command with the --crypto-erase switch is used +via ndctl. + +OVERWRITE +--------- +The overwrite operation wipes the entire nvdimm. Therefore it can take +a significant amount of time. To issue the command is very similar to disable +passphrase and secure erase. However, when the command returns successfully +it just means overwrite has been successfully started. The wait-overwrite +command for ndctl can be used to wait on the nvdimms that are performing +overwrite until the operation is completed. Upon successful completion of the +operation, wbinvd will be issued by the kernel. The "sanitize-dimm" command +with the --overwrite switch is used via ndctl. If both --crypto-erase and +--overwrite switches are passed in, the crypt-erase will be issued first before +overwrite. + +SECURITY FREEZE +--------------- +This operation requires no key to succeed. Ndctl will issue the DSM command +and upon completion, the security commands besides status query will be locked +out until the next boot. + +MASTER PASSPHRASE ENABLE, UPDATE, and CRYPTO ERASE +----------------------------------------------------------- +These operations are similar to the user passphrase enable and update. The only +difference is that a different encrypted key is being used for the master +passphrase operations. Note that master passphrase has no relation to the +master key for encryption. + + +[1] http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf +[2] https://www.kernel.org/doc/Documentation/security/keys/trusted-encrypted.rst diff --git a/Documentation/ndctl/ndctl-disable-passphrase.txt b/Documentation/ndctl/ndctl-disable-passphrase.txt index e921eb23..df7401cb 100644 --- a/Documentation/ndctl/ndctl-disable-passphrase.txt +++ b/Documentation/ndctl/ndctl-disable-passphrase.txt @@ -24,4 +24,6 @@ OPTIONS :: include::xable-dimm-options.txt[] +include::intel-nvdimm-security.txt[] + include::../copyright.txt[] diff --git a/Documentation/ndctl/ndctl-enable-passphrase.txt b/Documentation/ndctl/ndctl-enable-passphrase.txt index 6639ce8d..9ff19927 100644 --- a/Documentation/ndctl/ndctl-enable-passphrase.txt +++ b/Documentation/ndctl/ndctl-enable-passphrase.txt @@ -31,10 +31,14 @@ include::xable-dimm-options.txt[] -m:: --master-key=:: Key name for the master key used to seal the NVDIMM security keys. + The format would be : + i.e.: trusted:master-nvdimm -M:: --master-passphrase:: Parameter to indicate that we are managing the master passphrase instead of the user passphrase. +include::intel-nvdimm-security.txt[] + include::../copyright.txt[] diff --git a/Documentation/ndctl/ndctl-freeze-security.txt b/Documentation/ndctl/ndctl-freeze-security.txt index 4e9d2d61..2ae21980 100644 --- a/Documentation/ndctl/ndctl-freeze-security.txt +++ b/Documentation/ndctl/ndctl-freeze-security.txt @@ -17,4 +17,6 @@ DESCRIPTION Provide a generic interface to freeze the security for NVDIMM. Once security is frozen, no other security operations can succeed until reboot happens. +include::intel-nvdimm-security.txt[] + include::../copyright.txt[] diff --git a/Documentation/ndctl/ndctl-sanitize-dimm.txt b/Documentation/ndctl/ndctl-sanitize-dimm.txt index 7b036318..a8cdca71 100644 --- a/Documentation/ndctl/ndctl-sanitize-dimm.txt +++ b/Documentation/ndctl/ndctl-sanitize-dimm.txt @@ -39,4 +39,6 @@ include::xable-dimm-options.txt[] instead of the user passphrase. This only is applicable to the crypto-erase option. +include::intel-nvdimm-security.txt[] + include::../copyright.txt[] diff --git a/Documentation/ndctl/ndctl-update-passphrase.txt b/Documentation/ndctl/ndctl-update-passphrase.txt index e2ecacf5..046fac6c 100644 --- a/Documentation/ndctl/ndctl-update-passphrase.txt +++ b/Documentation/ndctl/ndctl-update-passphrase.txt @@ -35,4 +35,6 @@ include::xable-dimm-options.txt[] Parameter to indicate that we are managing the master passphrase instead of the user passphrase. +include::intel-nvdimm-security.txt[] + include::../copyright.txt[]