From: Dave Jiang <dave.jiang@intel.com> To: dan.j.williams@intel.com Cc: dhowells@redhat.com, alison.schofield@intel.com, keyrings@vger.kernel.org, keescook@chromium.org, linux-nvdimm@lists.01.org Subject: [PATCH v2 11/11] libnvdimm: adding documentation for nvdimm security support Date: Thu, 05 Jul 2018 13:23:12 -0700 [thread overview] Message-ID: <153082219238.61422.8691902999718036928.stgit@djiang5-desk3.ch.intel.com> (raw) In-Reply-To: <153082172527.61422.13689320279597181069.stgit@djiang5-desk3.ch.intel.com> Adding theory of operation for the security support that's going into libnvdimm. Signed-off-by: Dave Jiang <dave.jiang@intel.com> --- Documentation/nvdimm/security | 70 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 Documentation/nvdimm/security diff --git a/Documentation/nvdimm/security b/Documentation/nvdimm/security new file mode 100644 index 000000000000..756205c9aa4c --- /dev/null +++ b/Documentation/nvdimm/security @@ -0,0 +1,70 @@ +NVDIMM SECURITY +=============== + +1. Introduction +--------------- + +With the introduction of Intel DSM v1.7 specification [1], security DSMs are +introduced. The spec added the following security DSMs: "get security state", +"set passphrase", "disable passphrase", "unlock unit", "freeze lock", +"secure erase", and "overwrite". A security_ops data structure has been +added to struct dimm in order to support the security operations and generic +APIs are exposed to allow vendor neutral operations. + +2. Sysfs Interface +------------------ +The "security" sysfs attribute is provided in the nvdimm sysfs directory. For +example: +/sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security + +The "show" function of that attribute will display the security state for +that DIMM. The following states are available: disabled, unlocked, locked, +frozen, and unsupported. + +The "store" function takes several commands when the attribute is written to +in order to support some of the security functionalities: +update - enable security. Add or update current key. +disable - disable enabled security and remove key. +freeze - freeze changing of security states. +erase - generate new ecryption key for DIMM and crypto-scrambles all existing + user data. + +3. Key Management +----------------- + +The key is associted to the payload by the DIMM id. For example: +# cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id +8089-a2-1740-00000133 +The DIMM id would be provided along with the key payload (passphrase) to +the kernel. + +The security keys are managed on the basis of a single key per DIMM. The +key "passphrase" is expected to be 32bytes long or padded to 32bytes. This is +similar to the ATA security specification [2]. A key is initially acquired +via the request_key() kernel API call and retrieved from userspace. It is up to +the user to provide an upcall application to retrieve the key in whatever +fashion meets their security requirements. + +The payload provided to the key can be a 32bytes payload or 64bytes payload +when doing an "update". The payload is viewed as 64 bytes in the following +format: +[32 bytes current key data zero padded][32 bytes new key data zero padded] +However, a 32bytes payload can be provided and will be assumed as the old +key to be 32 bytes of 0s and the provided 32bytes payload is the new key. +It is up to the user upcall function how that's presented as the key payload +to the kernel. + +All the other security functions that require a provided key can accept a +32bytes payload or 64bytes. If the payload is 64bytes, then second 32bytes +will be ignored and the first 32bytes contains the expected "passphrase". + +4. Unlocking +------------ +When the DIMMs are being enumerated by the kernel, the kernel will attempt to +retrieve the key from its keyring. If that fails, it will attempt to +acquire the key from the userspace upcall function. This is the only time +a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked +until reboot. + +[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.7.pdf +[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf _______________________________________________ Linux-nvdimm mailing list Linux-nvdimm@lists.01.org https://lists.01.org/mailman/listinfo/linux-nvdimm
WARNING: multiple messages have this Message-ID (diff)
From: Dave Jiang <dave.jiang@intel.com> To: dan.j.williams@intel.com Cc: dhowells@redhat.com, alison.schofield@intel.com, keyrings@vger.kernel.org, keescook@chromium.org, linux-nvdimm@lists.01.org Subject: [PATCH v2 11/11] libnvdimm: adding documentation for nvdimm security support Date: Thu, 05 Jul 2018 20:23:12 +0000 [thread overview] Message-ID: <153082219238.61422.8691902999718036928.stgit@djiang5-desk3.ch.intel.com> (raw) In-Reply-To: <153082172527.61422.13689320279597181069.stgit@djiang5-desk3.ch.intel.com> Adding theory of operation for the security support that's going into libnvdimm. Signed-off-by: Dave Jiang <dave.jiang@intel.com> --- Documentation/nvdimm/security | 70 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 Documentation/nvdimm/security diff --git a/Documentation/nvdimm/security b/Documentation/nvdimm/security new file mode 100644 index 000000000000..756205c9aa4c --- /dev/null +++ b/Documentation/nvdimm/security @@ -0,0 +1,70 @@ +NVDIMM SECURITY +=======+ +1. Introduction +--------------- + +With the introduction of Intel DSM v1.7 specification [1], security DSMs are +introduced. The spec added the following security DSMs: "get security state", +"set passphrase", "disable passphrase", "unlock unit", "freeze lock", +"secure erase", and "overwrite". A security_ops data structure has been +added to struct dimm in order to support the security operations and generic +APIs are exposed to allow vendor neutral operations. + +2. Sysfs Interface +------------------ +The "security" sysfs attribute is provided in the nvdimm sysfs directory. For +example: +/sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/security + +The "show" function of that attribute will display the security state for +that DIMM. The following states are available: disabled, unlocked, locked, +frozen, and unsupported. + +The "store" function takes several commands when the attribute is written to +in order to support some of the security functionalities: +update - enable security. Add or update current key. +disable - disable enabled security and remove key. +freeze - freeze changing of security states. +erase - generate new ecryption key for DIMM and crypto-scrambles all existing + user data. + +3. Key Management +----------------- + +The key is associted to the payload by the DIMM id. For example: +# cat /sys/devices/LNXSYSTM:00/LNXSYBUS:00/ACPI0012:00/ndbus0/nmem0/nfit/id +8089-a2-1740-00000133 +The DIMM id would be provided along with the key payload (passphrase) to +the kernel. + +The security keys are managed on the basis of a single key per DIMM. The +key "passphrase" is expected to be 32bytes long or padded to 32bytes. This is +similar to the ATA security specification [2]. A key is initially acquired +via the request_key() kernel API call and retrieved from userspace. It is up to +the user to provide an upcall application to retrieve the key in whatever +fashion meets their security requirements. + +The payload provided to the key can be a 32bytes payload or 64bytes payload +when doing an "update". The payload is viewed as 64 bytes in the following +format: +[32 bytes current key data zero padded][32 bytes new key data zero padded] +However, a 32bytes payload can be provided and will be assumed as the old +key to be 32 bytes of 0s and the provided 32bytes payload is the new key. +It is up to the user upcall function how that's presented as the key payload +to the kernel. + +All the other security functions that require a provided key can accept a +32bytes payload or 64bytes. If the payload is 64bytes, then second 32bytes +will be ignored and the first 32bytes contains the expected "passphrase". + +4. Unlocking +------------ +When the DIMMs are being enumerated by the kernel, the kernel will attempt to +retrieve the key from its keyring. If that fails, it will attempt to +acquire the key from the userspace upcall function. This is the only time +a locked DIMM can be unlocked. Once unlocked, the DIMM will remain unlocked +until reboot. + +[1]: http://pmem.io/documents/NVDIMM_DSM_Interface-V1.7.pdf +[2]: http://www.t13.org/documents/UploadedDocuments/docs2006/e05179r4-ACS-SecurityClarifications.pdf
next prev parent reply other threads:[~2018-07-05 20:23 UTC|newest] Thread overview: 26+ messages / expand[flat|nested] mbox.gz Atom feed top 2018-07-05 20:22 [PATCH v2 00/11] Adding security support for nvdimm Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 01/11] nfit: adding support for Intel DSM 1.7 commands Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 02/11] libnvdimm: create keyring to store security keys Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 03/11] nfit/libnvdimm: store dimm id as a member to struct nvdimm Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 04/11] nfit/libnvdimm: adding unlock of nvdimm support for Intel DIMMs Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-09 22:52 ` Dan Williams 2018-07-09 22:52 ` Dan Williams 2018-07-05 20:22 ` [PATCH v2 05/11] nfit/libnvdimm: adding set passphrase support for Intel nvdimms Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 06/11] nfit/libnvdimm: adding disable passphrase support to Intel nvdimm Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 07/11] nfit/libnvdimm: adding freeze security " Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:22 ` [PATCH v2 08/11] nfit/libnvdimm: adding support for issue secure erase DSM " Dave Jiang 2018-07-05 20:22 ` Dave Jiang 2018-07-05 20:23 ` [PATCH v2 09/11] nfit_test: adding context to dimm_dev for nfit_test Dave Jiang 2018-07-05 20:23 ` Dave Jiang 2018-07-05 20:23 ` [PATCH v2 10/11] nfit_test: adding test support for Intel nvdimm security DSMs Dave Jiang 2018-07-05 20:23 ` Dave Jiang 2018-07-05 20:23 ` Dave Jiang [this message] 2018-07-05 20:23 ` [PATCH v2 11/11] libnvdimm: adding documentation for nvdimm security support Dave Jiang
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=153082219238.61422.8691902999718036928.stgit@djiang5-desk3.ch.intel.com \ --to=dave.jiang@intel.com \ --cc=alison.schofield@intel.com \ --cc=dan.j.williams@intel.com \ --cc=dhowells@redhat.com \ --cc=keescook@chromium.org \ --cc=keyrings@vger.kernel.org \ --cc=linux-nvdimm@lists.01.org \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: linkBe sure your reply has a Subject: header at the top and a blank line before the message body.
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.