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