1NDCTL-WAIT-OVERWRITE(1)          ndctl Manual          NDCTL-WAIT-OVERWRITE(1)
2
3
4

NAME

6       ndctl-wait-overwrite - wait for an overwrite operation to complete
7

SYNOPSIS

9       ndctl wait-overwrite <nmem0> [<nmem1>..<nmemN>] [<options>]
10

DESCRIPTION

12       The kernel provides a POLL(2) capable sysfs file (security) to indicate
13       the state of overwrite. This command waits for a change in the state of
14       this file across all specified dimms.
15

OPTIONS

17       <dimm>
18           A nmemX device name, or a dimm id number. Restrict the operation to
19           the specified dimm(s). The keyword all can be specified to indicate
20           the lack of any restriction, however this is the same as not
21           supplying a --dimm option at all.
22
23       -b, --bus=
24           A bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict
25           the operation to the specified bus(es). The keyword all can be
26           specified to indicate the lack of any restriction, however this is
27           the same as not supplying a --bus option at all.
28
29       -v, --verbose
30           Emit debug messages.
31

THEORY OF OPERATION

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

SEE ALSO

181       ndctl-sanitize-dimm(1)
182
183
184
185ndctl                             2019-10-28           NDCTL-WAIT-OVERWRITE(1)
Impressum