Documentation/nvdimm/security.txt

   1 NVDIMM SECURITY
   2 ===============
   3
   4 1. Introduction
   5 ---------------
   6
   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.
  13
  14 2. Sysfs Interface
  15 ------------------
  16 The "security" sysfs attribute is provided in the nvdimm sysfs directory. For
  17 example:
  18 /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security
  19
  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
  23 will not be visible.
  24
  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.
  34
  35 3. Key Management
  36 -----------------
  37
  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
  40 8089-a2-1740-00000133
  41 The DIMM id would be provided along with the key payload (passphrase) to
  42 the kernel.
  43
  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.
  49
  50 A nvdimm encrypted-key of format enc32 has the description format of:
  51 nvdimm:<bus-provider-specific-unique-id>
  52
  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.
  56
  57 4. Unlocking
  58 ------------
  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.
  67
  68 5. Update
  69 ---------
  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
  76 the format:
  77 update <old keyid> <new keyid>
  78
  79 If there is no old keyid due to a security enabling, then a 0 should be
  80 passed in.
  81
  82 6. Freeze
  83 ---------
  84 The freeze operation does not require any keys. The security config can be
  85 frozen by a user with root privelege.
  86
  87 7. Disable
  88 ----------
  89 The security disable command format is:
  90 disable <keyid>
  91
  92 An key with the current passphrase payload that is tied to the nvdimm should be
  93 in the kernel user keyring.
  94
  95 8. Secure Erase
  96 ---------------
  97 The command format for doing a secure erase is:
  98 erase <keyid>
  99
 100 An key with the current passphrase payload that is tied to the nvdimm should be
 101 in the kernel user keyring.
 102
 103 9. Overwrite
 104 ------------
 105 The command format for doing an overwrite is:
 106 overwrite <keyid>
 107
 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.
 110
 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.
 113
 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.
 116
 117 10. Master Update
 118 -----------------
 119 The command format for doing a master update is:
 120 update <old keyid> <new keyid>
 121
 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.
 125
 126 This command is only available when security is disabled.
 127
 128 11. Master Erase
 129 ----------------
 130 The command format for doing a master erase is:
 131 master_erase <current keyid>
 132
 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.
 136
 137 This command is only available when the master security is enabled, indicated
 138 by the extended security status.
 139
 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