From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga09.intel.com (mga09.intel.com [134.134.136.24]) (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 2492C2119623A for ; Fri, 30 Nov 2018 13:34:32 -0800 (PST) Subject: [PATCH v5 12/12] ndctl: documentation for security and key management From: Dave Jiang Date: Fri, 30 Nov 2018 14:34:30 -0700 Message-ID: <154361367067.6129.12362020358975253499.stgit@djiang5-desk3.ch.intel.com> In-Reply-To: <154361315118.6129.3346352930852675435.stgit@djiang5-desk3.ch.intel.com> References: <154361315118.6129.3346352930852675435.stgit@djiang5-desk3.ch.intel.com> MIME-Version: 1.0 List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Errors-To: linux-nvdimm-bounces@lists.01.org Sender: "Linux-nvdimm" To: dan.j.williams@intel.com, vishal.l.verma@intel.com Cc: linux-nvdimm@lists.01.org List-ID: Adding the theory of operation for Intel DSM operations. Signed-off-by: Dave Jiang --- Documentation/ndctl/intel-nvdimm-security.txt | 129 ++++++++++++++++++++++ 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, 139 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..a9c86d9c --- /dev/null +++ b/Documentation/ndctl/intel-nvdimm-security.txt @@ -0,0 +1,129 @@ +// SPDX-License-Identifier: GPL-2.0 + +THEORY OF OPERATOIN +------------------- +With the introduction of Intel 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 (trusted and encrypted keys [2]) and +involves 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 that's associated to the nvdimm +are disabled before proceeding except overwrite. Overwrite expects the nvdimm +also be disabled. + +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 also setup script has been provided by ndctl. When the +nvdimm driver probes, it will +1. 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. Create the unlock DSM and copy the decrypted payload into the DSM + passphrase field, and issue the DSM to unlock the DIMM. + +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 derypted payload. When the +encrypted key is created, a binary blob of the encrypted key is written to the +desginated 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 can 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 is used via ndctl. + +OVERWRITE +--------- +The overwrite operation wipes the entire nvdimm. Therefore it takes 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 overwirte 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 +is used via ndctl. + +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..f5b1025d 100644 --- a/Documentation/ndctl/ndctl-enable-passphrase.txt +++ b/Documentation/ndctl/ndctl-enable-passphrase.txt @@ -37,4 +37,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[] 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[] _______________________________________________ Linux-nvdimm mailing list Linux-nvdimm@lists.01.org https://lists.01.org/mailman/listinfo/linux-nvdimm