[PATCH v5 12/12] ndctl: documentation for security and key management

[Dave Jiang <dave.jiang@intel.com>]

Adding the theory of operation for Intel DSM operations.

Signed-off-by: Dave Jiang <dave.jiang@intel.com>
---
 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
 <dimm>::
 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