1NDCTL-FREEZE-SECUR(1)            ndctl Manual            NDCTL-FREEZE-SECUR(1)
2
3
4

NAME

6       ndctl-freeze-security - Set the given DIMM(s) to reject future security
7       operations
8

SYNOPSIS

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

DESCRIPTION

13       Prevent any further security operations on the given DIMMs until the
14       next reboot. This is used in scenarios where the administrator has
15       taken all expected security actions for the current boot and wants the
16       DIMM to enforce / lock the current state.
17

EXAMPLES

19           .ft C
20           $ ndctl list -d nmem0
21           [
22             {
23               "dev":"nmem0",
24               "id":"cdab-0a-07e0-ffffffff",
25               "handle":0,
26               "phys_id":0,
27               "security":"unlocked"
28             }
29           ]
30
31           $ ndctl freeze-security  nmem0
32           security froze 1 nmem.
33
34           $ ndctl list -d nmem0
35           [
36             {
37               "dev":"nmem0",
38               "id":"cdab-0a-07e0-ffffffff",
39               "handle":0,
40               "phys_id":0,
41               "security":"unlocked",
42               "security_frozen":true
43             },
44           ]
45           .ft
46
47

OPTIONS

49       <dimm>
50           A nmemX device name, or a dimm id number. Restrict the operation to
51           the specified dimm(s). The keyword all can be specified to indicate
52           the lack of any restriction, however this is the same as not
53           supplying a --dimm option at all.
54
55       -b, --bus=
56           A bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict
57           the operation to the specified bus(es). The keyword all can be
58           specified to indicate the lack of any restriction, however this is
59           the same as not supplying a --bus option at all.
60
61       -v, --verbose
62           Emit debug messages.
63

THEORY OF OPERATION

65       The Intel Device Specific Methods (DSM) specification v1.7 and v1.8 [1]
66       introduced the following security management operations: enable
67       passhprase, update passphrase, unlock DIMM, disable security, freeze
68       security, secure (crypto) erase, overwrite, master passphrase enable,
69       master passphrase update, and master passphrase secure erase.
70
71       The security management for NVDIMMs is comprised of two parts. The
72       front end uses the Linux key management framework (trusted and
73       encrypted keys [2]) to store the encrypted passphrases in the
74       kernel-managed keyring. The interface for this is the keyutils utility
75       which uses the key management APIs in the Linux kernel. The back end
76       takes the decrypted payload (which is the DIMM passphrase) and passes
77       it to the DIMM.
78
79       Unlike other DSMs which are composed by libndctl and sent to the kernel
80       via an ioctl, the security DSMs are managed through the security sysfs
81       attribute under the dimm device. A key-ID is written to the security
82       attribute and the kernel pulls the associated key material from the
83       user keyring that is maintained by the kernel.
84
85       The security process begins with the generation of a master key that is
86       used to seal (encrypt) the passphrase for the DIMM. There can either be
87       one common master key that is used to encrypt every DIMM’s passphrase,
88       or a separate key can be generated for each DIMM. The master key is
89       also referred to as the key-encryption-key (kek). The kek can either be
90       generated by the TPM (Trusted Platform Module) on the system, or
91       alternatively, the System Master Key can also be used as the kek
92
93       For testing purposes a user key with randomized payload can also be
94       used as a kek. See [2] for details. To perform any security operations,
95       it is expected that the kek has been added to the kernel’s user keyring
96       as shown in example below:
97
98
99           .ft C
100           # keyctl show
101           Session Keyring
102            736023423 --alswrv      0     0  keyring: _ses
103            675104189 --alswrv      0 65534   \_ keyring: _uid.0
104            680187394 --alswrv      0     0       \_ trusted: nvdimm-master
105           .ft
106
107
108       Before performing any of the security operations, all the regions
109       associated with the DIMM in question need to be disabled. For the
110       overwrite operation, in addition to the regions, the dimm also needs to
111       be disabled.
112
113       [1] http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf [2]
114       https://www.kernel.org/doc/Documentation/security/keys/trusted-encrypted.rst
115
116       The following sub-sections describe specifics of each security feature.
117
118   UNLOCK
119       Unlock is performed by the kernel, however a preparation step must
120       happen before the unlock DSM can be issued by the kernel. It is
121       expected that from the initramfs, a setup command (ndctl load-keys) is
122       executed before the libnvdimm module is loaded by modprobe. This
123       command will inject the kek and the encrypted passphrases into the
124       kernel’s user keyring. During the probe of the libnvdimm driver, it
125       will:
126
127        1. Check the security state of the device and see if the DIMM is
128           locked
129
130        2. Request the associated encrypted passphrase from the kernel’s user
131           key ring
132
133        3. Use the kek to decrypt the passphrase
134
135        4. Create the unlock DSM, copy the decrypted payload into the DSM
136
137        5. Issue the DSM to unlock the DIMM
138
139       If the DIMM is already unlocked, the kernel will attempt to revalidate
140       the passphrase. If we fail to revalidate the passphrase, the kernel
141       will freeze the security and disallow any further security
142       configuration changes. A kernel module parameter is available to
143       override this behavior.
144
145   SETUP USER PASSPHRASE
146       To setup the passphrase for a DIMM, it is expected that the kek to be
147       used is present in the kernel’s user keyring. The kek encrypts the DIMM
148       passphrase using the enc32 key format. The plaintext passphrase is
149       never provided by or made visible to the user. It is instead randomly
150       generated by the kernel and userspace does not have access to it. Upon
151       encryption, a binary blob of the passphrase is written to the
152       passphrase blob storage directory (/etc/ndctl/keys). The user is
153       responsible for backing up the passphrase blobs to a secure location.
154
155   UPDATE USER PASSPHRASE
156       The update user passphrase operation uses the same DSM command as
157       enable user passphrase. Most of the work is done on the key management
158       side. The user has the option of providing a new kek for the new
159       passphrase, but continuing to use the existing kek is also acceptable.
160       The following operations are performed for update-passphrase:
161
162        1. Remove the encrypted passphrase from the kernel’s user keyring.
163
164        2. Rename the passphrase blob to old.
165
166        3. Load this old passphrase blob into the keyring with an "old" name.
167
168        4. Create the new passphrase and encrypt with the kek.
169
170        5. Send DSM with the old and new decrypted passphrases.
171
172        6. Remove old passphrase and the passphrase blob from the keyring.
173
174   REMOVE USER PASSPHRASE
175       The key-ID for the passphrase to be removed is written to sysfs. The
176       kernel then sends the DSM to disable security, and the passphrase is
177       then removed from the keyring, and the associated passphrase blob is
178       deleted.
179
180   CRYPTO (SECURE) ERASE
181       This operation is similar to remove-passphrase. The kernel issues a
182       WBINVD instruction before and after the operation to ensure no data
183       corruption from a stale CPU cache. Use ndctl’s sanitize-dimm command
184       with the --crypto-erase option to perform this operation.
185
186   OVERWRITE
187       This is invoked using --overwrite option for ndctl sanitize-dimm. The
188       overwrite operation wipes the entire NVDIMM. The operation can take a
189       significant amount of time. NOTE: When the command returns
190       successfully, it just means overwrite has been successfully started,
191       and not that the overwrite is complete. Subsequently, 'ndctl
192       wait-overwrite’can be used to wait for the NVDIMMs that are performing
193       overwrite. Upon successful completion of an overwrite, the WBINVD
194       instruction is issued by the kernel. If both --crypto-erase and
195       --overwrite options are supplied, then crypto-erase is performed before
196       overwrite.
197
198   SECURITY FREEZE
199       This operation does not require a passphrase. This will cause any
200       security command other than a status query to be locked out until the
201       next boot.
202
203   MASTER PASSPHRASE SETUP, UPDATE, and CRYPTO ERASE
204       These operations are similar to the user passphrase enable and update.
205       The only difference is that a different passphrase is used. The master
206       passphrase has no relation to the master key (kek) which is used for
207       encryption of either passphrase.
208
210       Copyright © 2016 - 2020, Intel Corporation. License GPLv2: GNU GPL
211       version 2 http://gnu.org/licenses/gpl.html. This is free software: you
212       are free to change and redistribute it. There is NO WARRANTY, to the
213       extent permitted by law.
214
215
216
217ndctl 71.1                        01/26/2021             NDCTL-FREEZE-SECUR(1)
Impressum