7 With the introduction of Intel Device Specific Methods (DSM) v1.8
8 specification [1], security DSMs are introduced. The spec added the following
9 security DSMs: "get security state", "set passphrase", "disable passphrase",
10 "unlock unit", "freeze lock", "secure erase", and "overwrite". A security_ops
11 data structure has been added to struct dimm in order to support the security
12 operations and generic APIs are exposed to allow vendor neutral operations.
16 The "security" sysfs attribute is provided in the nvdimm sysfs directory. For
18 /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security
20 The "show" attribute of that attribute will display the security state for
21 that DIMM. The following states are available: disabled, unlocked, locked,
22 frozen, and overwrite. If security is not supported, the sysfs attribute
25 The "store" attribute takes several commands when it is being written to
26 in order to support some of the security functionalities:
27 update <old_keyid> <new_keyid> - enable or update passphrase.
28 disable <keyid> - disable enabled security and remove key.
29 freeze - freeze changing of security states.
30 erase <keyid> - delete existing user encryption key.
31 overwrite <keyid> - wipe the entire nvdimm.
32 master_update <keyid> <new_keyid> - enable or update master passphrase.
33 master_erase <keyid> - delete existing user encryption key.
38 The key is associated to the payload by the DIMM id. For example:
39 # cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id
41 The DIMM id would be provided along with the key payload (passphrase) to
44 The security keys are managed on the basis of a single key per DIMM. The
45 key "passphrase" is expected to be 32bytes long. This is similar to the ATA
46 security specification [2]. A key is initially acquired via the request_key()
47 kernel API call during nvdimm unlock. It is up to the user to make sure that
48 all the keys are in the kernel user keyring for unlock.
50 A nvdimm encrypted-key of format enc32 has the description format of:
51 nvdimm:<bus-provider-specific-unique-id>
53 See file ``Documentation/security/keys/trusted-encrypted.rst`` for creating
54 encrypted-keys of enc32 format. TPM usage with a master trusted key is
55 preferred for sealing the encrypted-keys.
59 When the DIMMs are being enumerated by the kernel, the kernel will attempt to
60 retrieve the key from the kernel user keyring. This is the only time
61 a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked
62 until reboot. Typically an entity (i.e. shell script) will inject all the
63 relevant encrypted-keys into the kernel user keyring during the initramfs phase.
64 This provides the unlock function access to all the related keys that contain
65 the passphrase for the respective nvdimms. It is also recommended that the
66 keys are injected before libnvdimm is loaded by modprobe.
70 When doing an update, it is expected that the existing key is removed from
71 the kernel user keyring and reinjected as different (old) key. It's irrelevant
72 what the key description is for the old key since we are only interested in the
73 keyid when doing the update operation. It is also expected that the new key
74 is injected with the description format described from earlier in this
75 document. The update command written to the sysfs attribute will be with
77 update <old keyid> <new keyid>
79 If there is no old keyid due to a security enabling, then a 0 should be
84 The freeze operation does not require any keys. The security config can be
85 frozen by a user with root privelege.
89 The security disable command format is:
92 An key with the current passphrase payload that is tied to the nvdimm should be
93 in the kernel user keyring.
97 The command format for doing a secure erase is:
100 An key with the current passphrase payload that is tied to the nvdimm should be
101 in the kernel user keyring.
105 The command format for doing an overwrite is:
108 Overwrite can be done without a key if security is not enabled. A key serial
109 of 0 can be passed in to indicate no key.
111 The sysfs attribute "security" can be polled to wait on overwrite completion.
112 Overwrite can last tens of minutes or more depending on nvdimm size.
114 An encrypted-key with the current user passphrase that is tied to the nvdimm
115 should be injected and its keyid should be passed in via sysfs.
119 The command format for doing a master update is:
120 update <old keyid> <new keyid>
122 The operating mechanism for master update is identical to update except the
123 master passphrase key is passed to the kernel. The master passphrase key
124 is just another encrypted-key.
126 This command is only available when security is disabled.
130 The command format for doing a master erase is:
131 master_erase <current keyid>
133 This command has the same operating mechanism as erase except the master
134 passphrase key is passed to the kernel. The master passphrase key is just
135 another encrypted-key.
137 This command is only available when the master security is enabled, indicated
138 by the extended security status.
140 [1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
141 [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf