NDCTL-FREEZE-SECURITY(1)

📦
version 85 · 16 versions
, in fedora 43, fedora 44, ubuntu stonking

💖 ndctl-freeze-security — the manual, but make it make sense 💖

okay bestie, so this is ndctl-freeze-security from the ndctl manual, and it's literally the "no take-backs" button for your DIMMs. let's get into it 🫶

✨ NAME ✨

ndctl-freeze-security — locks the given DIMM(s) so they reject any future security operations. it's giving "we're done here, thanks" 💅

🌸 SYNOPSIS 🌸

ndctl freeze-security <nmem0> [<nmem1>..<nmemN>] [<options>]

🦋 DESCRIPTION 🦋

So what this does is: it stops any further security operations on the DIMMs you point at, and it stays that way until the next reboot. periodt.

When would you even want this? When you're the admin, you've already done every security thing you were gonna do for this boot, and now you want the DIMM to just enforce and lock in the current state. no more changes, we're frozen, we're iconic 🧊✨

🎀 EXAMPLES 🎀

first, peep the state of nmem0:

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

now freeze it:

$ ndctl freeze-security  nmem0
security froze 1 nmem.

and look at the glow-up 😭💖:

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

see that "security_frozen":true? yeah. that's the whole vibe. locked. 👑

⭐ OPTIONS ⭐

  • <dimm> — a nmemX device name, or a dimm id number. restricts the operation to the dimm(s) you picked out. you can also throw in the keyword all to say "no restrictions at all" — but lowkey that's the exact same thing as just not passing a --dimm option, so. yeah. 🙈
  • -b, --bus= — a bus id number, or a provider string (like "ACPI.NFIT"). restricts the operation to the bus(es) you named. again, the keyword all means "no restriction whatsoever", which is identical to not supplying a --bus option at all. same energy, fr fr.
  • -v, --verbose — emits debug messages. for when you wanna see everything that's going on. nosy bestie behavior, and honestly? valid. 🔍

🌈 THEORY OF OPERATION 🌈

okay this is the lore drop, sit down, get comfy 🍓

The Intel Device Specific Methods (DSM) specification v1.7 and v1.8 [1] brought us these security management operations: enable passphrase, update passphrase, unlock DIMM, disable security, freeze security, secure (crypto) erase, overwrite, master passphrase enable, master passphrase update, and master passphrase secure erase. that's the whole menu.

The security management for NVDIMMs has 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 that 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 hands it over to the DIMM.

Now here's the thing that makes security DSMs different: 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 gets written to the security attribute, and the kernel pulls the associated key material from the user keyring that the kernel maintains. no ioctl, just sysfs. slay.

The security process starts with generating a master key that's used to seal (encrypt) the passphrase for the DIMM. You can either have one common master key encrypting every DIMM's passphrase, or you can generate a separate key for each DIMM. The master key is also called the key-encryption-key (kek). The kek can be generated by the TPM (Trusted Platform Module) on the system, or alternatively, the System Master Key can also be used as the kek

For testing purposes, a user key with a randomized payload can also be used as a kek. See [2] for details. And to perform any security operations, it's expected that the kek has been added to the kernel's user keyring, like in this example:

# keyctl show
Session Keyring
 736023423 --alswrv      0     0  keyring: _ses
 675104189 --alswrv      0 65534   \_ keyring: _uid.0
 680187394 --alswrv      0     0       \_ trusted: nvdimm-master

Before performing any of the security operations, all the regions associated with the DIMM in question need to be disabled. And for the overwrite operation, on top of the regions, the dimm itself also needs to be disabled. don't skip this step bestie, it matters 💀

The following sub-sections describe specifics of each security feature. 👇

🔓 UNLOCK

Unlock is performed by the kernel — but a prep step has to happen before the kernel can issue the unlock DSM. It's expected that, from the initramfs, a setup command (ndctl load-keys) is executed before the libnvdimm module is loaded by modprobe. This command injects the kek and the encrypted passphrases into the kernel's user keyring. Then, 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 revalidate the passphrase. And if that revalidation fails, the kernel will freeze the security and disallow any further security configuration changes. 😱 There is a kernel module parameter available to override this behavior, if you really must.

🔑 SETUP USER PASSPHRASE

To set up the passphrase for a DIMM, it's expected that the kek you're gonna use is present in the kernel's user keyring. The kek encrypts the DIMM passphrase using the enc32 key format. The plaintext passphrase is never provided by the user or made visible to the user — nope, it's randomly generated by the kernel, and userspace does not have access to it. Once it's encrypted, a binary blob of the passphrase gets written to the passphrase blob storage directory (/etc/ndctl/keys). And you are responsible for backing up those passphrase blobs to a secure location. that part is on you, bestie 🫶

♻️ UPDATE USER PASSPHRASE

The update user passphrase operation uses the same DSM command as enable user passphrase. Most of the work actually happens on the key management side. You've got the option of providing a new kek for the new passphrase, but continuing to use the existing kek is also totally acceptable. Here's what gets 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 USER PASSPHRASE

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. bye bye 👋

💥 CRYPTO (SECURE) ERASE

This operation is similar to remove-passphrase. The kernel issues a WBINVD instruction before and after the operation to make sure there's no data corruption from a stale CPU cache. To do this, use ndctl's sanitize-dimm command with the --crypto-erase option. ✨

🧹 OVERWRITE

This one is invoked using the --overwrite option for ndctl sanitize-dimm. The overwrite operation wipes the entire NVDIMM. Heads up: the operation can take a significant amount of time.

NOTE: When the command returns successfully, it just means overwrite has been successfully started — not that the overwrite is complete. do not be fooled bestie 😭

After that, ndctl wait-overwrite can be used to wait for the NVDIMMs that are performing overwrite. Upon successful completion of an overwrite, the WBINVD instruction is issued by the kernel. And if you supply both --crypto-erase and --overwrite options, then crypto-erase is performed before overwrite. order matters, iykyk.

🧊 SECURITY FREEZE

This is the one this whole page is about! This operation does not require a passphrase. It will cause any security command other than a status query to be locked out until the next boot. that's it. that's the whole thing. no key needed, just vibes and consequences 💅

👑 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 passphrase is used. And important: the master passphrase has no relation to the master key (kek) which is used for encryption of either passphrase. don't confuse them, they're two different queens fr fr 👑

Copyright © 2016 - 2022, Intel Corporation. License GPLv2: GNU GPL version 2 http://gnu.org/licenses/gpl.html. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

and that's the whole page, bestie 🥰 this was ndctl-freeze-security(1), page from the ndctl manual, and the version/date on the bottom of the original is ndctl / 2026-07-07 — so consider that your lil timestamp. go freeze some security, stay hydrated, and remember: regions disabled first. mwah 💖✨🦋

📦 where this page comes from