1NDCTL-REMOVE-PASSPHRASE(1) ndctl Manual NDCTL-REMOVE-PASSPHRASE(1)
2
6 ndctl-remove-passphrase - Stop a DIMM from locking at power-loss and
7 requiring a passphrase to access media
8
10 ndctl remove-passphrase <nmem0> [<nmem1>..<nmemN>] [<options>]
11
13 Search the user keyring for an encrypted passphrase for the NVDIMM in
14 question. If not found, attempt to load the passphrase blob. After
15 disabling the passphrase, remove the key-ID from the keyring as well as
16 the passphrase blob from the file system.
17
19 <dimm>
20 A 'nmemX' device name, or a dimm id number. The keyword 'all' can
22 be specified to carry out the operation on every dimm in the system,
23 optionally filtered by bus id (see --bus= option).
24 -b, --bus=
26 Enforce that the operation only be carried on devices that are
27 attached to the given bus. Where bus can be a provider name or a
28 bus id number.
29 -v, --verbose
31 Emit debug messages.
32
34 The Intel Device Specific Methods (DSM) specification v1.7 and v1.8 [1]
35 introduced the following security management operations: enable
36 passhprase, update passphrase, unlock DIMM, disable security, freeze
37 security, secure (crypto) erase, overwrite, master passphrase enable,
38 master passphrase update, and master passphrase secure erase.
39 The security management for NVDIMMs is comprised of two parts. The
41 front end uses the Linux key management framework (trusted and
42 encrypted keys [2]) to store the encrypted passphrases in the
43 kernel-managed keyring. The interface for this is the keyutils utility
44 which uses the key management APIs in the Linux kernel. The back end
45 takes the decrypted payload (which is the DIMM passphrase) and passes
46 it to the DIMM.
47 Unlike other DSMs which are composed by libndctl and sent to the kernel
49 via an ioctl, the security DSMs are managed through the security sysfs
50 attribute under the dimm device. A key-ID is written to the security
51 attribute and the kernel pulls the associated key material from the
52 user keyring that is maintained by the kernel.
53 The security process begins with the generation of a master key that is
55 used to seal (encrypt) the passphrase for the DIMM. There can either be
56 one common master key that is used to encrypt every DIMM’s passphrase,
57 or a separate key can be generated for each DIMM. The master key is
58 also referred to as the key-encryption-key (kek). The kek can either be
59 generated by the TPM (Trusted Platform Module) on the system, or
60 alternatively, the System Master Key can also be used as the kek
61 For testing purposes a user key with randomized payload can also be
63 used as a kek. See [2] for details. To perform any security operations,
64 it is expected that the kek has been added to the kernel’s user keyring
65 as shown in example below:
66 # keyctl show
68 Session Keyring
69 736023423 --alswrv 0 0 keyring: _ses
70 675104189 --alswrv 0 65534 \_ keyring: _uid.0
71 680187394 --alswrv 0 0 \_ trusted: nvdimm-master
72 Before performing any of the security operations, all the regions
74 associated with the DIMM in question need to be disabled. For the
75 overwrite operation, in addition to the regions, the dimm also needs to
76 be disabled.
77 [1] <http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf>
79 [2] <https://www.kernel.org/doc/Documentation/security/keys/
80 trusted-encrypted.rst>
81 The following sub-sections describe specifics of each security feature.
83 UNLOCK
85 Unlock is performed by the kernel, however a preparation step must
86 happen before the unlock DSM can be issued by the kernel. It is
87 expected that from the initramfs, a setup command (ndctl load-keys) is
88 executed before the libnvdimm module is loaded by modprobe. This
89 command will inject the kek and the encrypted passphrases into the
90 kernel’s user keyring. During the probe of the libnvdimm driver, it
91 will:
92 1. Check the security state of the device and see if the DIMM is
94 locked
95 2. Request the associated encrypted passphrase from the kernel’s user
97 key ring
98 3. Use the kek to decrypt the passphrase
100 4. Create the unlock DSM, copy the decrypted payload into the DSM
102 5. Issue the DSM to unlock the DIMM
104 If the DIMM is already unlocked, the kernel will attempt to revalidate
106 the passphrase. If we fail to revalidate the passphrase, the kernel
107 will freeze the security and disallow any further security
108 configuration changes. A kernel module parameter is available to
109 override this behavior.
110 SETUP USER PASSPHRASE
112 To setup the passphrase for a DIMM, it is expected that the kek to be
113 used is present in the kernel’s user keyring. The kek encrypts the DIMM
114 passphrase using the enc32 key format. The plaintext passphrase is
115 never provided by or made visible to the user. It is instead randomly
116 generated by the kernel and userspace does not have access to it. Upon
117 encryption, a binary blob of the passphrase is written to the
118 passphrase blob storage directory (/etc/ndctl/keys). The user is
119 responsible for backing up the passphrase blobs to a secure location.
120 UPDATE USER PASSPHRASE
122 The update user passphrase operation uses the same DSM command as
123 enable user passphrase. Most of the work is done on the key management
124 side. The user has the option of providing a new kek for the new
125 passphrase, but continuing to use the existing kek is also acceptable.
126 The following operations are performed for update-passphrase:
127 1. Remove the encrypted passphrase from the kernel’s user keyring.
129 2. Rename the passphrase blob to old.
131 3. Load this old passphrase blob into the keyring with an "old" name.
133 4. Create the new passphrase and encrypt with the kek.
135 5. Send DSM with the old and new decrypted passphrases.
137 6. Remove old passphrase and the passphrase blob from the keyring.
139 REMOVE USER PASSPHRASE
141 The key-ID for the passphrase to be removed is written to sysfs. The
142 kernel then sends the DSM to disable security, and the passphrase is
143 then removed from the keyring, and the associated passphrase blob is
144 deleted.
145 CRYPTO (SECURE) ERASE
147 This operation is similar to remove-passphrase. The kernel issues a
148 WBINVD instruction before and after the operation to ensure no data
149 corruption from a stale CPU cache. Use ndctl’s sanitize-dimm command
150 with the --crypto-erase option to perform this operation.
151 OVERWRITE
153 This is invoked using --overwrite option for ndctl sanitize-dimm. The
154 overwrite operation wipes the entire NVDIMM. The operation can take a
155 significant amount of time. NOTE: When the command returns
156 successfully, it just means overwrite has been successfully started,
157 and not that the overwrite is complete. Subsequently, 'ndctl
158 wait-overwrite’can be used to wait for the NVDIMMs that are performing
159 overwrite. Upon successful completion of an overwrite, the WBINVD
160 instruction is issued by the kernel. If both --crypto-erase and
161 --overwrite options are supplied, then crypto-erase is performed before
162 overwrite.
163 SECURITY FREEZE
165 This operation does not require a passphrase. This will cause any
166 security command other than a status query to be locked out until the
167 next boot.
168 MASTER PASSPHRASE SETUP, UPDATE, and CRYPTO ERASE
170 These operations are similar to the user passphrase enable and update.
171 The only difference is that a different passphrase is used. The master
172 passphrase has no relation to the master key (kek) which is used for
173 encryption of either passphrase.
174
176 Copyright (c) 2016 - 2019, Intel Corporation. License GPLv2: GNU GPL
177 version 2 <http://gnu.org/licenses/gpl.html>. This is free software:
178 you are free to change and redistribute it. There is NO WARRANTY, to
179 the extent permitted by law.
180
182 ndctl-setup-passphrase(1), ndctl-update-passphrase(1)
183ndctl 2019-05-10 NDCTL-REMOVE-PASSPHRASE(1)