From patchwork Wed Jan 9 17:54:57 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Dave Jiang X-Patchwork-Id: 10754741 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 7F7D214E5 for ; Wed, 9 Jan 2019 17:55:01 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 6CAAD284E8 for ; Wed, 9 Jan 2019 17:55:01 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 5D9E428AF4; Wed, 9 Jan 2019 17:55:01 +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 92FDA284E8 for ; Wed, 9 Jan 2019 17:55:00 +0000 (UTC) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 88C53211B5A4F; Wed, 9 Jan 2019 09:55:00 -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=192.55.52.136; helo=mga12.intel.com; envelope-from=dave.jiang@intel.com; receiver=linux-nvdimm@lists.01.org Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) (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 F2265211B5A4F for ; Wed, 9 Jan 2019 09:54:58 -0800 (PST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga008.jf.intel.com ([10.7.209.65]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 09 Jan 2019 09:54:58 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,458,1539673200"; d="scan'208";a="108593198" Received: from djiang5-desk3.ch.intel.com ([143.182.136.93]) by orsmga008.jf.intel.com with ESMTP; 09 Jan 2019 09:54:57 -0800 Subject: [PATCH v7 12/12] ndctl: documentation for security and key management From: Dave Jiang To: vishal.l.verma@intel.com, dan.j.williams@intel.com Date: Wed, 09 Jan 2019 10:54:57 -0700 Message-ID: <154705649779.23227.12078996055659175218.stgit@djiang5-desk3.ch.intel.com> In-Reply-To: <154705633843.23227.15903675663299735878.stgit@djiang5-desk3.ch.intel.com> References: <154705633843.23227.15903675663299735878.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 Add a "Theory of Operation" section describing the Intel DSM operations to the relevant man pages. Signed-off-by: Dave Jiang --- Documentation/ndctl/intel-nvdimm-security.txt | 140 ++++++++++++++++++++++ Documentation/ndctl/ndctl-disable-passphrase.txt | 2 Documentation/ndctl/ndctl-enable-passphrase.txt | 2 Documentation/ndctl/ndctl-freeze-security.txt | 2 Documentation/ndctl/ndctl-sanitize-dimm.txt | 2 Documentation/ndctl/ndctl-update-passphrase.txt | 2 6 files changed, 150 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..b8443e12 --- /dev/null +++ b/Documentation/ndctl/intel-nvdimm-security.txt @@ -0,0 +1,140 @@ +// 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. The operations supported by +ndctl are 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 'unlock' DSM is not supported by ndctl, that is left for the kernel to +manage with some assistance from userspace. + +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's 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 key from the Trusted Platform +Module (TPM), but a master key generated by the TPM can also +be used. 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 minimum the master key is already +in the kernel's 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 + +Except for 'overwrite', all operations expect the relevant regions associated +with the nvdimm are disabled before proceeding. For 'overwrite', in addition +to the regions, the dimm itself is expected to be disabled. + +The following 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. This script script will inject the master key and the +related encrypted keys into the kernel's user key ring. A reference modprobe +config file and a setup script have been provided by ndctl. During the 'probe' +of the nvdimm driver, 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's user key ring. +3. Finally, create the unlock DSM, 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's user key ring and the master key name is passed to +ndctl so it can do key management. An encrypted key with a 32 bytes 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's 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 side. 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 +operations are performed for update: +1. Remove the associated encrypted key from the kernel's user key ring. +2. Rename the key blob to old. +3. Load the now old key blob into kernel's 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 +----------------------- +The current key id is written to sysfs by ndctl. Upon successfully disabling +the passphrase, the key is removed from the kernel's user keyring, and the +associated key blob is deleted. + +CRYPTO (SECURE) ERASE +--------------------- +This operation is similar to passphrase-disable. The kernel will issue +WBINVD before and after the operation to ensure no data corruption from a stale +CPU cache. Use ndctl's sanitize-dimm command with the --crypto-erase option to +perform this operation. + +OVERWRITE +--------- +The overwrite operation wipes the entire nvdimm. The operation can take +a significant amount of time. Issuing a command is very similar to +"passphrase-disable" 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 option is used via ndctl. +If both --crypto-erase and --overwrite options 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 3c8bfe47..2654bb7c 100644 --- a/Documentation/ndctl/ndctl-disable-passphrase.txt +++ b/Documentation/ndctl/ndctl-disable-passphrase.txt @@ -29,4 +29,6 @@ include::xable-dimm-options.txt[] Path to where key related files resides. This parameter is optional and the default is set to /etc/ndctl/keys. +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 c025b1c3..54a2716e 100644 --- a/Documentation/ndctl/ndctl-enable-passphrase.txt +++ b/Documentation/ndctl/ndctl-enable-passphrase.txt @@ -44,4 +44,6 @@ include::xable-dimm-options.txt[] Indicates 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 f8ffb42c..ee1e3d58 100644 --- a/Documentation/ndctl/ndctl-sanitize-dimm.txt +++ b/Documentation/ndctl/ndctl-sanitize-dimm.txt @@ -44,4 +44,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 8b5dfe01..dc5f33c0 100644 --- a/Documentation/ndctl/ndctl-update-passphrase.txt +++ b/Documentation/ndctl/ndctl-update-passphrase.txt @@ -40,4 +40,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[]