0001 ===============
0002 NVDIMM Security
0003 ===============
0004
0005 1. Introduction
0006 ---------------
0007
0008 With the introduction of Intel Device Specific Methods (DSM) v1.8
0009 specification [1], security DSMs are introduced. The spec added the following
0010 security DSMs: "get security state", "set passphrase", "disable passphrase",
0011 "unlock unit", "freeze lock", "secure erase", and "overwrite". A security_ops
0012 data structure has been added to struct dimm in order to support the security
0013 operations and generic APIs are exposed to allow vendor neutral operations.
0014
0015 2. Sysfs Interface
0016 ------------------
0017 The "security" sysfs attribute is provided in the nvdimm sysfs directory. For
0018 example:
0019 /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security
0020
0021 The "show" attribute of that attribute will display the security state for
0022 that DIMM. The following states are available: disabled, unlocked, locked,
0023 frozen, and overwrite. If security is not supported, the sysfs attribute
0024 will not be visible.
0025
0026 The "store" attribute takes several commands when it is being written to
0027 in order to support some of the security functionalities:
0028 update <old_keyid> <new_keyid> - enable or update passphrase.
0029 disable <keyid> - disable enabled security and remove key.
0030 freeze - freeze changing of security states.
0031 erase <keyid> - delete existing user encryption key.
0032 overwrite <keyid> - wipe the entire nvdimm.
0033 master_update <keyid> <new_keyid> - enable or update master passphrase.
0034 master_erase <keyid> - delete existing user encryption key.
0035
0036 3. Key Management
0037 -----------------
0038
0039 The key is associated to the payload by the DIMM id. For example:
0040 # cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id
0041 8089-a2-1740-00000133
0042 The DIMM id would be provided along with the key payload (passphrase) to
0043 the kernel.
0044
0045 The security keys are managed on the basis of a single key per DIMM. The
0046 key "passphrase" is expected to be 32bytes long. This is similar to the ATA
0047 security specification [2]. A key is initially acquired via the request_key()
0048 kernel API call during nvdimm unlock. It is up to the user to make sure that
0049 all the keys are in the kernel user keyring for unlock.
0050
0051 A nvdimm encrypted-key of format enc32 has the description format of:
0052 nvdimm:<bus-provider-specific-unique-id>
0053
0054 See file ``Documentation/security/keys/trusted-encrypted.rst`` for creating
0055 encrypted-keys of enc32 format. TPM usage with a master trusted key is
0056 preferred for sealing the encrypted-keys.
0057
0058 4. Unlocking
0059 ------------
0060 When the DIMMs are being enumerated by the kernel, the kernel will attempt to
0061 retrieve the key from the kernel user keyring. This is the only time
0062 a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked
0063 until reboot. Typically an entity (i.e. shell script) will inject all the
0064 relevant encrypted-keys into the kernel user keyring during the initramfs phase.
0065 This provides the unlock function access to all the related keys that contain
0066 the passphrase for the respective nvdimms. It is also recommended that the
0067 keys are injected before libnvdimm is loaded by modprobe.
0068
0069 5. Update
0070 ---------
0071 When doing an update, it is expected that the existing key is removed from
0072 the kernel user keyring and reinjected as different (old) key. It's irrelevant
0073 what the key description is for the old key since we are only interested in the
0074 keyid when doing the update operation. It is also expected that the new key
0075 is injected with the description format described from earlier in this
0076 document. The update command written to the sysfs attribute will be with
0077 the format:
0078 update <old keyid> <new keyid>
0079
0080 If there is no old keyid due to a security enabling, then a 0 should be
0081 passed in.
0082
0083 6. Freeze
0084 ---------
0085 The freeze operation does not require any keys. The security config can be
0086 frozen by a user with root privelege.
0087
0088 7. Disable
0089 ----------
0090 The security disable command format is:
0091 disable <keyid>
0092
0093 An key with the current passphrase payload that is tied to the nvdimm should be
0094 in the kernel user keyring.
0095
0096 8. Secure Erase
0097 ---------------
0098 The command format for doing a secure erase is:
0099 erase <keyid>
0100
0101 An key with the current passphrase payload that is tied to the nvdimm should be
0102 in the kernel user keyring.
0103
0104 9. Overwrite
0105 ------------
0106 The command format for doing an overwrite is:
0107 overwrite <keyid>
0108
0109 Overwrite can be done without a key if security is not enabled. A key serial
0110 of 0 can be passed in to indicate no key.
0111
0112 The sysfs attribute "security" can be polled to wait on overwrite completion.
0113 Overwrite can last tens of minutes or more depending on nvdimm size.
0114
0115 An encrypted-key with the current user passphrase that is tied to the nvdimm
0116 should be injected and its keyid should be passed in via sysfs.
0117
0118 10. Master Update
0119 -----------------
0120 The command format for doing a master update is:
0121 update <old keyid> <new keyid>
0122
0123 The operating mechanism for master update is identical to update except the
0124 master passphrase key is passed to the kernel. The master passphrase key
0125 is just another encrypted-key.
0126
0127 This command is only available when security is disabled.
0128
0129 11. Master Erase
0130 ----------------
0131 The command format for doing a master erase is:
0132 master_erase <current keyid>
0133
0134 This command has the same operating mechanism as erase except the master
0135 passphrase key is passed to the kernel. The master passphrase key is just
0136 another encrypted-key.
0137
0138 This command is only available when the master security is enabled, indicated
0139 by the extended security status.
0140
0141 [1]: https://pmem.io/documents/NVDIMM_DSM_Interface-V1.8.pdf
0142
0143 [2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
