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