NVDIMMs that provide additional security mechanisms, such as the Inte(R) Optane(TM) DC Persistent Memory Modules, can be managed using the ndctl utility and the following sub-commands:

• ndctl-load-keys

• ndctl-freeze-security

• ndctl-remove-passphrase

• ndctl-sanitize-dimm

• ndctl-setup-passphrase

• ndctl-update-passphrase

The Intel(R) Device Specific Methods (DSM) specification v1.7 and v1.8 introduced the following security management operations: enable passhprase, update passphrase, unlock DIMM, disable security, freeze security, secure (crypto) erase, overwrite, master passphrase enable, master passphrase update, and master passphrase secure erase.

The security management for NVDIMMs is comprised of two parts. The front end uses the Linux key management framework (trusted and encrypted keys [2]) to store the encrypted passphrases in the kernel-managed keyring. The interface for this is the keyutils utility which uses the key management APIs in the Linux kernel. The back end takes the decrypted payload (which is the DIMM passphrase) and passes it to the DIMM.

Unlike other DSMs which are composed by libndctl and sent to the kernel via an ioctl, the security DSMs are managed through the security sysfs attribute under the dimm device. A key-ID is written to the security attribute and the kernel pulls the associated key material from the user keyring that is maintained by the kernel.

The security process begins with the generation of a master key that is used to seal (encrypt) the passphrase for the DIMM. There can either be one common master key that is used to encrypt every DIMM’s passphrase, or a separate key can be generated for each DIMM. The master key is also referred to as the key-encryption-key (kek). The kek can either be generated by the TPM (Trusted Platform Module) on the system, or alternatively, the System Master Key can also be used as the kek

Setup a User Passphrase

The ndctl setup-passphrase is used to setup and enable a security passphrase for one or more NVDIMMs.

To setup the passphrase for a NVDIMM or interleaved set of NVDIMMs, it is expected that the master key has previously been loaded into the user keyring. More information on how this can be done can be found in the kernel documentation at: https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html. The kek encrypts the NVDIMM passphrase using the enc32 key format. The plaintext passphrase is never provided by or made visible to the user. It is instead randomly generated by the kernel and userspace does not have access to it. Upon encryption, a binary blob of the passphrase is written to the passphrase blob storage directory (/etc/ndctl/keys). The user is responsible for backing up the passphrase blobs to a secure location. The command will fail if the passphrase is already in the user keyring or if a passphrase blob already exists in /etc/ndctl/keys.

Update a User Passphrase

The ndctl update-passphrase command updates the security passphrase for one or more NVDIMMs that have previously been setup using the ndctl setup-passphrase command. Prerequisites for this command to succeed:

1. The kek has been loaded into the kernel’s user keyring

2. setup-passphrase has successfully been executed on the NVDIMM(s) and the NVDIMM is unlocked

The updated key blobs will be created in the /etc/ndctl/keys directory with a file name format of "nvdimm.blob".

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 has the option of providing a new kek for the new passphrase, but continuing to use the existing kek is also acceptable. The following operations are performed for update-passphrase:

1. Remove the encrypted passphrase from the kernel’s user keyring.

2. Rename the passphrase blob to old.

3. Load this old passphrase blob into the keyring with an “old” name.

4. Create the new passphrase and encrypt with the kek.

5. Send DSM with the old and new decrypted passphrases.

6. Remove old passphrase and the passphrase blob from the keyring.

Remove a User Passphrase

The ndctl remove-passphrase command prevents a DIMM from locking at power-loss and requiring a passphrase to access media.

The key-ID for the passphrase to be removed is written to sysfs. The kernel then sends the DSM to disable security, and the passphrase is then removed from the keyring, and the associated passphrase blob is deleted.

Crypto (Secure) Erase NVDIMMs

This operation is similar to ndctl remove-passphrase. The kernel issues a WBINVD instruction before and after the operation to ensure no data corruption from a stale CPU cache. Use the ndctl sanitize-dimm command with the --crypto-erase option to perform this operation.

The ndctl sanitize-dimm command performs a cryptographic destruction of the contents of the given NVDIMM. It scrambles the data, and any metadata or info-blocks, but it doesn’t modify namespace labels. Therefore, any namespaces on regions associated with the given NVDIMM will be retained, but they will end up in the raw mode.

Additionally, after completion of this command, the security and passphrase for the given NVDIMM will be disabled, and the passphrase and any key material will also be removed from the keyring and the ndctl keys directory at /etc/ndctl/keys

The command supports two different methods of performing the cryptographic erase. The default is crypto-erase, but additionally, an overwrite option is available which overwrites not only the data area, but also the label area, thus losing record of any namespaces the given NVDIMM participates in.

Overwriting (Sanitizing) NVDIMMs

One or more NVDIMMs can be sanitized using ndctl sanitize-dimm [--crypto-erase][--overwrite]. The command supports two different methods of performing the cryptographic erase. The default is crypto-erase, but additionally, an overwrite option is available which overwrites not only the data area, but also the label area, thus losing record of any namespaces the given NVDIMM participates in.

The overwrite operation wipes the entire NVDIMM(s) and can take a significant amount of time depending on the size of the device(s) and number of devices. When the command returns successfully, it just means overwrite has been successfully started, the overwrite operation continues asynchronously in the background. Use the ndctl wait-overwrite command to wait for the NVDIMMs that are performing overwrite. Upon successful completion of an overwrite, the WBINVD instruction is issued by the kernel. If both –crypto-erase and –overwrite options are supplied, then crypto-erase is performed before overwrite.

Security Freeze

The ndctl freeze-security command does not require a passphrase. This will cause any security command other than a status query to be locked out until the next boot. This is used in scenarios where the administrator has taken all expected security actions for the current boot and wants the NVDIMMs to enforce/lock the current state until system reboot.

To check the current security status of a single NVDIMM (nmem{X} device):

$ ndctl list -d nmem0
[
  {
    "dev":"nmem0",
    "id":"cdab-0a-07e0-ffffffff",
    "handle":0,
    "phys_id":0,
    "security":"unlocked"
  }
]

To freeze a single NVDIMM:

$ ndctl freeze-security nmem0
security freezed 1 nmem.
​
$ ndctl list -d nmem0
[
  {
    "dev":"nmem0",
    "id":"cdab-0a-07e0-ffffffff",
    "handle":0,
    "phys_id":0,
    "security":"frozen"
  }
]

Unlock NVDIMMs

Unlock is performed by the kernel, however a preparation step must happen before the unlock DSM can be issued by the kernel. It is expected that from the initramfs, a setup command ndctl load-keys is executed before the libnvdimm module is loaded by modprobe. See the 'Loading Keys' section. This command will inject the kek and the encrypted passphrases into the kernel’s user keyring. During the probe of the libnvdimm driver, it will:

1. Check the security state of the device and see if the DIMM is locked

2. Request the associated encrypted passphrase from the kernel’s user key ring

3. Use the kek to decrypt the passphrase

4. Create the unlock DSM, copy the decrypted payload into the DSM

5. Issue the DSM to unlock the DIMM

If the DIMM is already unlocked, the kernel will attempt to re-validate the passphrase. If we fail to revalidate the passphrase, the kernel will freeze the security and disallow any further security configuration changes. A kernel module parameter is available to override this behavior.

Loading Keys

The load-keys command loads the master key (kek) and the encrypted passphrases for all NVDIMMs into the user keyring maintained by the kernel. The command is expected to be called during initialization and before the libnvdimm kernel module is loaded, typically from an initrd. This is typically set up using a modprobe config that calls the command before module load.

See https://www.kernel.org/doc/Documentation/security/keys/trusted-encrypted.rst for more information on the Kernel implementation.

Master Passphrase - Setup, Update, and Crypto Erase

These operations are similar to creating and updating the user passphrase. The only difference is that a different passphrase is used. Both setup-passphrase and update-passphrase support the -m flag to differentiate between user and master passphrase operations. The master passphrase has no relation to the master key (kek) which is used for encryption of either passphrase. More information about the master key can be found in the kernel documentation at: https://www.kernel.org/doc/html/latest/security/keys/trusted-encrypted.html.