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

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

Add a "Theory of Operation" section describing the Intel DSM operations to
the relevant man pages.

Signed-off-by: Dave Jiang <dave.jiang@intel.com>
---
 Documentation/ndctl/intel-nvdimm-security.txt   |  141 +++++++++++++++++++++++
 Documentation/ndctl/ndctl-freeze-security.txt   |    2 
 Documentation/ndctl/ndctl-remove-passphrase.txt |    2 
 Documentation/ndctl/ndctl-sanitize-dimm.txt     |    2 
 Documentation/ndctl/ndctl-setup-passphrase.txt  |    2 
 Documentation/ndctl/ndctl-update-passphrase.txt |    3 
 6 files changed, 152 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..dc114df9
--- /dev/null
+++ b/Documentation/ndctl/intel-nvdimm-security.txt
@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: GPL-2.0
+
+include::attrs.adoc[]
+
+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.
+
+SETUP USER PASSPHRASE
+----------------------
+To setup 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
+key blob storage directory ({ndctl_keysdir}). 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.
+
+REMOVE 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 SETUP, 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-freeze-security.txt b/Documentation/ndctl/ndctl-freeze-security.txt
index d14b8a39..43ea81eb 100644
--- a/Documentation/ndctl/ndctl-freeze-security.txt
+++ b/Documentation/ndctl/ndctl-freeze-security.txt
@@ -55,4 +55,6 @@ OPTIONS
 <dimm>::
 include::xable-dimm-options.txt[]
 
+include::intel-nvdimm-security.txt[]
+
 include::../copyright.txt[]
diff --git a/Documentation/ndctl/ndctl-remove-passphrase.txt b/Documentation/ndctl/ndctl-remove-passphrase.txt
index 17ff905b..df83eaee 100644
--- a/Documentation/ndctl/ndctl-remove-passphrase.txt
+++ b/Documentation/ndctl/ndctl-remove-passphrase.txt
@@ -23,4 +23,6 @@ OPTIONS
 <dimm>::
 include::xable-dimm-options.txt[]
 
+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 78e1eb37..06ce06c8 100644
--- a/Documentation/ndctl/ndctl-sanitize-dimm.txt
+++ b/Documentation/ndctl/ndctl-sanitize-dimm.txt
@@ -43,6 +43,8 @@ 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[]
 
 SEE ALSO
diff --git a/Documentation/ndctl/ndctl-setup-passphrase.txt b/Documentation/ndctl/ndctl-setup-passphrase.txt
index 613e17a1..76b55492 100644
--- a/Documentation/ndctl/ndctl-setup-passphrase.txt
+++ b/Documentation/ndctl/ndctl-setup-passphrase.txt
@@ -49,4 +49,6 @@ include::xable-dimm-options.txt[]
 --verbose::
         Emit debug messages for the namespace check process.
 
+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 8b5fc812..2a43f2bb 100644
--- a/Documentation/ndctl/ndctl-update-passphrase.txt
+++ b/Documentation/ndctl/ndctl-update-passphrase.txt
@@ -48,6 +48,9 @@ include::xable-dimm-options.txt[]
 -v::
 --verbose::
         Emit debug messages for the namespace check process.
+
+include::intel-nvdimm-security.txt[]
+
 include::../copyright.txt[]
 
 SEE ALSO:

_______________________________________________
Linux-nvdimm mailing list
Linux-nvdimm@lists.01.org
https://lists.01.org/mailman/listinfo/linux-nvdimm