1 =============== 1 ===============
2 NVDIMM Security 2 NVDIMM Security
3 =============== 3 ===============
4 4
5 1. Introduction 5 1. Introduction
6 --------------- 6 ---------------
7 7
8 With the introduction of Intel Device Specific 8 With the introduction of Intel Device Specific Methods (DSM) v1.8
9 specification [1], security DSMs are introduce 9 specification [1], security DSMs are introduced. The spec added the following
10 security DSMs: "get security state", "set pass 10 security DSMs: "get security state", "set passphrase", "disable passphrase",
11 "unlock unit", "freeze lock", "secure erase", 11 "unlock unit", "freeze lock", "secure erase", and "overwrite". A security_ops
12 data structure has been added to struct dimm i 12 data structure has been added to struct dimm in order to support the security
13 operations and generic APIs are exposed to all 13 operations and generic APIs are exposed to allow vendor neutral operations.
14 14
15 2. Sysfs Interface 15 2. Sysfs Interface
16 ------------------ 16 ------------------
17 The "security" sysfs attribute is provided in 17 The "security" sysfs attribute is provided in the nvdimm sysfs directory. For
18 example: 18 example:
19 /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012: 19 /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security
20 20
21 The "show" attribute of that attribute will di 21 The "show" attribute of that attribute will display the security state for
22 that DIMM. The following states are available: 22 that DIMM. The following states are available: disabled, unlocked, locked,
23 frozen, and overwrite. If security is not supp 23 frozen, and overwrite. If security is not supported, the sysfs attribute
24 will not be visible. 24 will not be visible.
25 25
26 The "store" attribute takes several commands w 26 The "store" attribute takes several commands when it is being written to
27 in order to support some of the security funct 27 in order to support some of the security functionalities:
28 update <old_keyid> <new_keyid> - enable or upd 28 update <old_keyid> <new_keyid> - enable or update passphrase.
29 disable <keyid> - disable enabled security and 29 disable <keyid> - disable enabled security and remove key.
30 freeze - freeze changing of security states. 30 freeze - freeze changing of security states.
31 erase <keyid> - delete existing user encryptio 31 erase <keyid> - delete existing user encryption key.
32 overwrite <keyid> - wipe the entire nvdimm. 32 overwrite <keyid> - wipe the entire nvdimm.
33 master_update <keyid> <new_keyid> - enable or 33 master_update <keyid> <new_keyid> - enable or update master passphrase.
34 master_erase <keyid> - delete existing user en 34 master_erase <keyid> - delete existing user encryption key.
35 35
36 3. Key Management 36 3. Key Management
37 ----------------- 37 -----------------
38 38
39 The key is associated to the payload by the DI 39 The key is associated to the payload by the DIMM id. For example:
40 # cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACP 40 # cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id
41 8089-a2-1740-00000133 41 8089-a2-1740-00000133
42 The DIMM id would be provided along with the k 42 The DIMM id would be provided along with the key payload (passphrase) to
43 the kernel. 43 the kernel.
44 44
45 The security keys are managed on the basis of 45 The security keys are managed on the basis of a single key per DIMM. The
46 key "passphrase" is expected to be 32bytes lon 46 key "passphrase" is expected to be 32bytes long. This is similar to the ATA
47 security specification [2]. A key is initially 47 security specification [2]. A key is initially acquired via the request_key()
48 kernel API call during nvdimm unlock. It is up 48 kernel API call during nvdimm unlock. It is up to the user to make sure that
49 all the keys are in the kernel user keyring fo 49 all the keys are in the kernel user keyring for unlock.
50 50
51 A nvdimm encrypted-key of format enc32 has the 51 A nvdimm encrypted-key of format enc32 has the description format of:
52 nvdimm:<bus-provider-specific-unique-id> 52 nvdimm:<bus-provider-specific-unique-id>
53 53
54 See file ``Documentation/security/keys/trusted 54 See file ``Documentation/security/keys/trusted-encrypted.rst`` for creating
55 encrypted-keys of enc32 format. TPM usage with 55 encrypted-keys of enc32 format. TPM usage with a master trusted key is
56 preferred for sealing the encrypted-keys. 56 preferred for sealing the encrypted-keys.
57 57
58 4. Unlocking 58 4. Unlocking
59 ------------ 59 ------------
60 When the DIMMs are being enumerated by the ker 60 When the DIMMs are being enumerated by the kernel, the kernel will attempt to
61 retrieve the key from the kernel user keyring. 61 retrieve the key from the kernel user keyring. This is the only time
62 a locked DIMM can be unlocked. Once unlocked, 62 a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked
63 until reboot. Typically an entity (i.e. shell 63 until reboot. Typically an entity (i.e. shell script) will inject all the
64 relevant encrypted-keys into the kernel user k 64 relevant encrypted-keys into the kernel user keyring during the initramfs phase.
65 This provides the unlock function access to al 65 This provides the unlock function access to all the related keys that contain
66 the passphrase for the respective nvdimms. It 66 the passphrase for the respective nvdimms. It is also recommended that the
67 keys are injected before libnvdimm is loaded b 67 keys are injected before libnvdimm is loaded by modprobe.
68 68
69 5. Update 69 5. Update
70 --------- 70 ---------
71 When doing an update, it is expected that the 71 When doing an update, it is expected that the existing key is removed from
72 the kernel user keyring and reinjected as diff 72 the kernel user keyring and reinjected as different (old) key. It's irrelevant
73 what the key description is for the old key si 73 what the key description is for the old key since we are only interested in the
74 keyid when doing the update operation. It is a 74 keyid when doing the update operation. It is also expected that the new key
75 is injected with the description format descri 75 is injected with the description format described from earlier in this
76 document. The update command written to the s 76 document. The update command written to the sysfs attribute will be with
77 the format: 77 the format:
78 update <old keyid> <new keyid> 78 update <old keyid> <new keyid>
79 79
80 If there is no old keyid due to a security ena 80 If there is no old keyid due to a security enabling, then a 0 should be
81 passed in. 81 passed in.
82 82
83 6. Freeze 83 6. Freeze
84 --------- 84 ---------
85 The freeze operation does not require any keys 85 The freeze operation does not require any keys. The security config can be
86 frozen by a user with root privilege. 86 frozen by a user with root privilege.
87 87
88 7. Disable 88 7. Disable
89 ---------- 89 ----------
90 The security disable command format is: 90 The security disable command format is:
91 disable <keyid> 91 disable <keyid>
92 92
93 An key with the current passphrase payload tha 93 An key with the current passphrase payload that is tied to the nvdimm should be
94 in the kernel user keyring. 94 in the kernel user keyring.
95 95
96 8. Secure Erase 96 8. Secure Erase
97 --------------- 97 ---------------
98 The command format for doing a secure erase is 98 The command format for doing a secure erase is:
99 erase <keyid> 99 erase <keyid>
100 100
101 An key with the current passphrase payload tha 101 An key with the current passphrase payload that is tied to the nvdimm should be
102 in the kernel user keyring. 102 in the kernel user keyring.
103 103
104 9. Overwrite 104 9. Overwrite
105 ------------ 105 ------------
106 The command format for doing an overwrite is: 106 The command format for doing an overwrite is:
107 overwrite <keyid> 107 overwrite <keyid>
108 108
109 Overwrite can be done without a key if securit 109 Overwrite can be done without a key if security is not enabled. A key serial
110 of 0 can be passed in to indicate no key. 110 of 0 can be passed in to indicate no key.
111 111
112 The sysfs attribute "security" can be polled t 112 The sysfs attribute "security" can be polled to wait on overwrite completion.
113 Overwrite can last tens of minutes or more dep 113 Overwrite can last tens of minutes or more depending on nvdimm size.
114 114
115 An encrypted-key with the current user passphr 115 An encrypted-key with the current user passphrase that is tied to the nvdimm
116 should be injected and its keyid should be pas 116 should be injected and its keyid should be passed in via sysfs.
117 117
118 10. Master Update 118 10. Master Update
119 ----------------- 119 -----------------
120 The command format for doing a master update i 120 The command format for doing a master update is:
121 update <old keyid> <new keyid> 121 update <old keyid> <new keyid>
122 122
123 The operating mechanism for master update is i 123 The operating mechanism for master update is identical to update except the
124 master passphrase key is passed to the kernel. 124 master passphrase key is passed to the kernel. The master passphrase key
125 is just another encrypted-key. 125 is just another encrypted-key.
126 126
127 This command is only available when security i 127 This command is only available when security is disabled.
128 128
129 11. Master Erase 129 11. Master Erase
130 ---------------- 130 ----------------
131 The command format for doing a master erase is 131 The command format for doing a master erase is:
132 master_erase <current keyid> 132 master_erase <current keyid>
133 133
134 This command has the same operating mechanism 134 This command has the same operating mechanism as erase except the master
135 passphrase key is passed to the kernel. The ma 135 passphrase key is passed to the kernel. The master passphrase key is just
136 another encrypted-key. 136 another encrypted-key.
137 137
138 This command is only available when the master 138 This command is only available when the master security is enabled, indicated
139 by the extended security status. 139 by the extended security status.
140 140
141 [1]: https://pmem.io/documents/NVDIMM_DSM_Inte 141 [1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
142 142
143 [2]: http://www.t13.org/documents/UploadedDocu 143 [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.