1NDCTL-UPDATE-PASSPHRASE(1)       ndctl Manual       NDCTL-UPDATE-PASSPHRASE(1)
2
3
4

NAME

6       ndctl-update-passphrase - update the security passphrase for an NVDIMM
7

SYNOPSIS

9       ndctl update-passphrase <nmem0> [<nmem1>..<nmemN>] [<options>]
10

DESCRIPTION

12       Update the security passphrase for one or more NVDIMMs. Prerequisites
13       for command to succeed:
14
15        1. The kek has been loaded into the kernel’s user keyring.
16
17        2. setup-passphrase has successfully been executed on the NVDIMM.
18
19           ·   Alternatively, the NVDIMM is unlocked.
20
21       The updated key blobs will be created in the /etc/ndctl/keys directory
22       with a file name format of "nvdimm_<dimm-unique-id>_<hostname>.blob".
23

OPTIONS

25       <dimm>
26           A nmemX device name, or a dimm id number. Restrict the operation to
27           the specified dimm(s). The keyword all can be specified to indicate
28           the lack of any restriction, however this is the same as not
29           supplying a --dimm option at all.
30
31       -b, --bus=
32           A bus id number, or a provider string (e.g. "ACPI.NFIT"). Restrict
33           the operation to the specified bus(es). The keyword all can be
34           specified to indicate the lack of any restriction, however this is
35           the same as not supplying a --bus option at all.
36
37       -k, --key_handle=
38           Handle for the master kek (key-encryption-key) that will be used
39           for sealing the passphrase(s) for the given DIMM(s). The format is:
40           <key type>:<key description>
41             e.g. trusted:nvdimm-master
42           NOTE: The kek is expected to have been loaded into the user
43           keyring.
44
45       -m, --master-passphrase
46           Indicates that we are managing the master passphrase instead of the
47           user passphrase.
48
49       -v, --verbose
50           Emit debug messages.
51

THEORY OF OPERATION

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

SEE ALSO:

201       ndctl-setup-passphrase(1), ndctl-remove-passphrase(1)
202
203
204
205ndctl                             2019-10-28        NDCTL-UPDATE-PASSPHRASE(1)
Impressum