1NDCTL-FREEZE-SECURITY(1)         ndctl Manual         NDCTL-FREEZE-SECURITY(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           $ ndctl list -d nmem0
20           [
21             {
22               "dev":"nmem0",
23               "id":"cdab-0a-07e0-ffffffff",
24               "handle":0,
25               "phys_id":0,
26               "security":"unlocked"
27             }
28           ]
29
30           $ ndctl freeze-security  nmem0
31           security freezed 1 nmem.
32
33           $ ndctl list -d nmem0
34           [
35             {
36               "dev":"nmem0",
37               "id":"cdab-0a-07e0-ffffffff",
38               "handle":0,
39               "phys_id":0,
40               "security":"frozen"
41             }
42           ]
43

OPTIONS

45       <dimm>
46
47               A 'nmemX' device name, or a dimm id number. The keyword 'all' can
48               be specified to carry out the operation on every dimm in the system,
49               optionally filtered by bus id (see --bus= option).
50
51       -b, --bus=
52           Enforce that the operation only be carried on devices that are
53           attached to the given bus. Where bus can be a provider name or a
54           bus id number.
55
56       -v, --verbose
57           Emit debug messages.
58

THEORY OF OPERATION

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