From: "Chang S. Bae" <chang.seok.bae@intel.com>
To: linux-kernel@vger.kernel.org, linux-crypto@vger.kernel.org,
dm-devel@redhat.com
Cc: ebiggers@kernel.org, gmazyland@gmail.com, luto@kernel.org,
dave.hansen@linux.intel.com, tglx@linutronix.de, bp@suse.de,
mingo@kernel.org, x86@kernel.org, herbert@gondor.apana.org.au,
ardb@kernel.org, dan.j.williams@intel.com,
bernie.keany@intel.com, charishma1.gairuboyina@intel.com,
lalithambika.krishnakumar@intel.com, chang.seok.bae@intel.com,
Ingo Molnar <mingo@redhat.com>, Borislav Petkov <bp@alien8.de>,
"H. Peter Anvin" <hpa@zytor.com>,
Jonathan Corbet <corbet@lwn.net>,
linux-doc@vger.kernel.org
Subject: [PATCH v6 01/12] Documentation/x86: Document Key Locker
Date: Mon, 10 Apr 2023 15:59:25 -0700 [thread overview]
Message-ID: <20230410225936.8940-2-chang.seok.bae@intel.com> (raw)
In-Reply-To: <20230410225936.8940-1-chang.seok.bae@intel.com>
Document the overview of the feature along with relevant consideration when
provisioning dm-crypt volumes with AES-KL instead of AES-NI.
Signed-off-by: Chang S. Bae <chang.seok.bae@intel.com>
Reviewed-by: Dan Williams <dan.j.williams@intel.com>
Cc: Thomas Gleixner <tglx@linutronix.de>
Cc: Ingo Molnar <mingo@redhat.com>
Cc: Borislav Petkov <bp@alien8.de>
Cc: Dave Hansen <dave.hansen@linux.intel.com>
Cc: "H. Peter Anvin" <hpa@zytor.com>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: x86@kernel.org
Cc: linux-doc@vger.kernel.org
Cc: linux-kernel@vger.kernel.org
---
Changes from v5:
* Fix a typo: 'feature feature' -> 'feature'
Changes from RFC v2:
* Add as a new patch.
The preview is available here:
https://htmlpreview.github.io/?https://github.com/intel-staging/keylocker/kdoc/x86/keylocker.html
---
Documentation/x86/index.rst | 1 +
Documentation/x86/keylocker.rst | 98 +++++++++++++++++++++++++++++++++
2 files changed, 99 insertions(+)
create mode 100644 Documentation/x86/keylocker.rst
diff --git a/Documentation/x86/index.rst b/Documentation/x86/index.rst
index 8ac64d7de4dc..669c239c009f 100644
--- a/Documentation/x86/index.rst
+++ b/Documentation/x86/index.rst
@@ -43,3 +43,4 @@ x86-specific Documentation
features
elf_auxvec
xstate
+ keylocker
diff --git a/Documentation/x86/keylocker.rst b/Documentation/x86/keylocker.rst
new file mode 100644
index 000000000000..3b405fade7d8
--- /dev/null
+++ b/Documentation/x86/keylocker.rst
@@ -0,0 +1,98 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+==============
+x86 Key Locker
+==============
+
+Introduction
+============
+
+Key Locker is a CPU feature to reduce key exfiltration opportunities
+while maintaining a programming interface similar to AES-NI. It
+converts the AES key into an encoded form, called the 'key handle'.
+The key handle is a wrapped version of the clear-text key where the
+wrapping key has limited exposure. Once converted, all subsequent data
+encryption using new AES instructions (AES-KL) uses this key handle,
+reducing the exposure of private key material in memory.
+
+Internal Wrapping Key (IWKey)
+=============================
+
+The CPU-internal wrapping key is an entity in a software-invisible CPU
+state. On every system boot, a new key is loaded. So the key handle that
+was encoded by the old wrapping key is no longer usable on system shutdown
+or reboot.
+
+And the key may be lost on the following exceptional situation upon wakeup:
+
+IWKey Restore Failure
+---------------------
+
+The CPU state is volatile with the ACPI S3/4 sleep states. When the system
+supports those states, the key has to be backed up so that it is restored
+on wake up. The kernel saves the key in non-volatile media.
+
+The event of an IWKey restore failure upon resume from suspend, all
+established key handles become invalid. In flight dm-crypt operations
+receive error results from pending operations. In the likely scenario that
+dm-crypt is hosting the root filesystem the recovery is identical to if a
+storage controller failed to resume from suspend, reboot. If the volume
+impacted by an IWKey restore failure is a data-volume then it is possible
+that I/O errors on that volume do not bring down the rest of the system.
+However, a reboot is still required because the kernel will have
+soft-disabled Key Locker. Upon the failure, the crypto library code will
+return -ENODEV on every AES-KL function call. The Key Locker implementation
+only loads a new IWKey at initial boot, not any time after like resume from
+suspend.
+
+Use Case and Non-use Cases
+==========================
+
+Bare metal disk encryption is the only intended use case.
+
+Userspace usage is not supported because there is no ABI provided to
+communicate and coordinate wrapping-key restore failure to userspace. For
+now, key restore failures are only coordinated with kernel users. But the
+kernel can not prevent userspace from using the feature's AES instructions
+('AES-KL') when the feature has been enabled. So, the lack of userspace
+support is only documented, not actively enforced.
+
+Key Locker is not expected to be advertised to guest VMs and the kernel
+implementation ignores it even if the VMM enumerates the capability. The
+expectation is that a guest VM wants private IWKey state, but the
+architecture does not provide that. An emulation of that capability, by
+caching per VM IWKeys in memory, defeats the purpose of Key Locker. The
+backup / restore facility is also not performant enough to be suitable for
+guest VM context switches.
+
+AES Instruction Set
+===================
+
+The feature accompanies a new AES instruction set. This instruction set is
+analogous to AES-NI. A set of AES-NI instructions can be mapped to an
+AES-KL instruction. For example, AESENC128KL is responsible for ten rounds
+of transformation, which is equivalent to nine times AESENC and one
+AESENCLAST in AES-NI.
+
+But they have some notable differences:
+
+* AES-KL provides a secure data transformation using an encrypted key.
+
+* If an invalid key handle is provided, e.g. a corrupted one or a handle
+ restriction failure, the instruction fails with setting RFLAGS.ZF. The
+ crypto library implementation includes the flag check to return an error
+ code. Note that the flag is also set when the internal wrapping key is
+ changed because of missing backup.
+
+* AES-KL implements support for 128-bit and 256-bit keys, but there is no
+ AES-KL instruction to process an 192-bit key. But there is no AES-KL
+ instruction to process a 192-bit key. The AES-KL cipher implementation
+ logs a warning message with a 192-bit key and then falls back to AES-NI.
+ So, this 192-bit key-size limitation is only documented, not enforced. It
+ means the key will remain in clear-text in memory. This is to meet Linux
+ crypto-cipher expectation that each implementation must support all the
+ AES-compliant key sizes.
+
+* Some AES-KL hardware implementation may have noticeable performance
+ overhead when compared with AES-NI instructions.
+
--
2.17.1
next prev parent reply other threads:[~2023-04-10 23:11 UTC|newest]
Thread overview: 147+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-01-12 21:12 [PATCH v5 00/12] x86: Support Key Locker Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 01/12] Documentation/x86: Document " Chang S. Bae
2023-06-05 10:52 ` Bagas Sanjaya
2022-01-12 21:12 ` [PATCH v5 02/12] x86/cpufeature: Enumerate Key Locker feature Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 03/12] x86/insn: Add Key Locker instructions to the opcode map Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 04/12] x86/asm: Add a wrapper function for the LOADIWKEY instruction Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 05/12] x86/msr-index: Add MSRs for Key Locker internal wrapping key Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 06/12] x86/keylocker: Define Key Locker CPUID leaf Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 07/12] x86/cpu/keylocker: Load an internal wrapping key at boot-time Chang S. Bae
2022-08-23 15:49 ` Evan Green
2022-08-24 22:20 ` Chang S. Bae
2022-08-24 22:52 ` Evan Green
2022-08-25 1:06 ` Chang S. Bae
2022-08-25 15:31 ` Evan Green
2022-08-31 23:08 ` Chang S. Bae
2022-09-06 16:22 ` Evan Green
2022-09-06 16:46 ` Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 08/12] x86/PM/keylocker: Restore internal wrapping key on resume from ACPI S3/4 Chang S. Bae
2022-01-29 17:31 ` [PATCH v5-fix " Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 09/12] x86/cpu: Add a configuration and command line option for Key Locker Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 10/12] crypto: x86/aes - Prepare for a new AES implementation Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 11/12] crypto: x86/aes-kl - Support AES algorithm using Key Locker instructions Chang S. Bae
2022-01-12 21:12 ` [PATCH v5 12/12] crypto: x86/aes-kl - Support XTS mode Chang S. Bae
2022-01-13 22:16 ` [PATCH v5 00/12] x86: Support Key Locker Dave Hansen
2022-01-13 22:34 ` Bae, Chang Seok
2023-04-10 22:59 ` [PATCH v6 " Chang S. Bae
2023-04-10 22:59 ` Chang S. Bae [this message]
2023-04-10 22:59 ` [PATCH v6 02/12] x86/cpufeature: Enumerate Key Locker feature Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 03/12] x86/insn: Add Key Locker instructions to the opcode map Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 04/12] x86/asm: Add a wrapper function for the LOADIWKEY instruction Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 05/12] x86/msr-index: Add MSRs for Key Locker internal wrapping key Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 06/12] x86/keylocker: Define Key Locker CPUID leaf Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 07/12] x86/cpu/keylocker: Load an internal wrapping key at boot-time Chang S. Bae
2023-05-05 23:05 ` Eric Biggers
2023-05-08 18:18 ` Chang S. Bae
2023-05-08 21:56 ` Dave Hansen
2023-05-09 0:31 ` Chang S. Bae
2023-05-09 0:51 ` Dave Hansen
2023-05-08 19:18 ` Elliott, Robert (Servers)
2023-05-08 20:15 ` Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 08/12] x86/PM/keylocker: Restore internal wrapping key on resume from ACPI S3/4 Chang S. Bae
2023-05-05 23:09 ` Eric Biggers
2023-05-08 18:18 ` Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 09/12] x86/cpu: Add a configuration and command line option for Key Locker Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 10/12] crypto: x86/aes - Prepare for a new AES implementation Chang S. Bae
2023-05-05 23:27 ` Eric Biggers
2023-05-09 0:55 ` Chang S. Bae
2023-05-11 19:05 ` Chang S. Bae
2023-05-11 21:39 ` Eric Biggers
2023-05-11 23:19 ` Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 11/12] crypto: x86/aes-kl - Support AES algorithm using Key Locker instructions Chang S. Bae
2023-05-06 0:01 ` Eric Biggers
2023-05-08 18:18 ` Chang S. Bae
2023-05-24 17:18 ` Chang S. Bae
2023-05-12 17:52 ` Milan Broz
2023-05-08 19:21 ` Elliott, Robert (Servers)
2023-05-08 19:24 ` Elliott, Robert (Servers)
2023-05-08 20:00 ` Chang S. Bae
2023-04-10 22:59 ` [PATCH v6 12/12] crypto: x86/aes-kl - Support XTS mode Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 00/12] x86: Support Key Locker Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 01/12] Documentation/x86: Document " Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 02/12] x86/cpufeature: Enumerate Key Locker feature Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 03/12] x86/insn: Add Key Locker instructions to the opcode map Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 04/12] x86/asm: Add a wrapper function for the LOADIWKEY instruction Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 05/12] x86/msr-index: Add MSRs for Key Locker wrapping key Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 06/12] x86/keylocker: Define Key Locker CPUID leaf Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 07/12] x86/cpu/keylocker: Load a wrapping key at boot-time Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 08/12] x86/PM/keylocker: Restore the wrapping key on the resume from ACPI S3/4 Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 09/12] x86/cpu: Add a configuration and command line option for Key Locker Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 10/12] crypto: x86/aesni - Use the proper data type in struct aesni_xts_ctx Chang S. Bae
2023-05-26 6:54 ` Eric Biggers
2023-05-30 20:50 ` Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 11/12] crypto: x86/aes - Prepare for a new AES implementation Chang S. Bae
2023-05-24 16:57 ` [PATCH v7 12/12] crypto: x86/aes-kl - Implement the AES-XTS algorithm Chang S. Bae
2023-05-26 7:23 ` Eric Biggers
2023-05-30 20:49 ` Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 00/12] x86: Support Key Locker Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 01/12] Documentation/x86: Document " Chang S. Bae
2023-06-05 10:54 ` Bagas Sanjaya
2023-06-06 2:17 ` Randy Dunlap
2023-06-06 4:18 ` Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 02/12] x86/cpufeature: Enumerate Key Locker feature Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 03/12] x86/insn: Add Key Locker instructions to the opcode map Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 04/12] x86/asm: Add a wrapper function for the LOADIWKEY instruction Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 05/12] x86/msr-index: Add MSRs for Key Locker wrapping key Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 06/12] x86/keylocker: Define Key Locker CPUID leaf Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 07/12] x86/cpu/keylocker: Load a wrapping key at boot-time Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 08/12] x86/PM/keylocker: Restore the wrapping key on the resume from ACPI S3/4 Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 09/12] x86/cpu: Add a configuration and command line option for Key Locker Chang S. Bae
2023-06-03 16:37 ` Borislav Petkov
2023-06-04 22:13 ` Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 10/12] crypto: x86/aesni - Use the proper data type in struct aesni_xts_ctx Chang S. Bae
2023-06-04 15:34 ` Eric Biggers
2023-06-04 22:02 ` Chang S. Bae
2023-06-05 2:46 ` Eric Biggers
2023-06-05 4:41 ` Chang S. Bae
2023-06-21 12:06 ` [PATCH] crypto: x86/aesni: Align the address before aes_set_key_common() Chang S. Bae
2023-07-14 8:51 ` Herbert Xu
2023-06-03 15:22 ` [PATCH v8 11/12] crypto: x86/aes - Prepare for a new AES-XTS implementation Chang S. Bae
2023-06-03 15:22 ` [PATCH v8 12/12] crypto: x86/aes-kl - Implement the AES-XTS algorithm Chang S. Bae
2023-06-07 5:35 ` Eric Biggers
2023-06-07 22:06 ` Chang S. Bae
2024-03-11 21:32 ` [PATCH] crypto: x86/aesni - Update aesni_set_key() to return void Chang S. Bae
2024-03-12 2:15 ` Eric Biggers
2024-03-12 7:46 ` Ard Biesheuvel
2024-03-12 15:03 ` Chang S. Bae
2024-03-12 15:18 ` Ard Biesheuvel
2024-03-12 15:37 ` Chang S. Bae
2024-03-22 23:04 ` [PATCH v2 0/2] crypto: x86/aesni - Simplify AES key expansion code Chang S. Bae
2024-03-22 23:04 ` [PATCH v2 1/2] crypto: x86/aesni - Rearrange AES key size check Chang S. Bae
2024-03-22 23:04 ` [PATCH v2 2/2] crypto: x86/aesni - Update aesni_set_key() to return void Chang S. Bae
2024-03-28 10:57 ` [PATCH v2 0/2] crypto: x86/aesni - Simplify AES key expansion code Herbert Xu
2024-03-29 1:53 ` [PATCH v9 00/14] x86: Support Key Locker Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 01/14] Documentation/x86: Document " Chang S. Bae
2024-03-31 15:48 ` Randy Dunlap
2024-03-29 1:53 ` [PATCH v9 02/14] x86/cpufeature: Enumerate Key Locker feature Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 03/14] x86/insn: Add Key Locker instructions to the opcode map Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 04/14] x86/asm: Add a wrapper function for the LOADIWKEY instruction Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 05/14] x86/msr-index: Add MSRs for Key Locker wrapping key Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 06/14] x86/keylocker: Define Key Locker CPUID leaf Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 07/14] x86/cpu/keylocker: Load a wrapping key at boot time Chang S. Bae
2024-04-07 23:04 ` [PATCH v9a " Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 08/14] x86/PM/keylocker: Restore the wrapping key on the resume from ACPI S3/4 Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 09/14] x86/hotplug/keylocker: Ensure wrapping key backup capability Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 10/14] x86/cpu/keylocker: Check Gather Data Sampling mitigation Chang S. Bae
2024-03-29 6:57 ` Pawan Gupta
2024-04-07 23:04 ` [PATCH v9a " Chang S. Bae
2024-04-19 0:01 ` Pawan Gupta
2024-04-22 7:49 ` Chang S. Bae
2024-04-19 17:47 ` [PATCH 15/14] x86/gds: Lock GDS mitigation when keylocker feature is present Pawan Gupta
2024-04-19 18:03 ` Daniel Sneddon
2024-04-19 20:19 ` Pawan Gupta
2024-04-19 20:33 ` Daniel Sneddon
2024-04-22 7:35 ` Chang S. Bae
2024-04-22 21:32 ` Pawan Gupta
2024-04-22 22:13 ` Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 11/14] x86/cpu/keylocker: Check Register File Data Sampling mitigation Chang S. Bae
2024-03-29 6:20 ` Pawan Gupta
2024-04-07 23:04 ` [PATCH v9a " Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 12/14] x86/Kconfig: Add a configuration for Key Locker Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 13/14] crypto: x86/aes - Prepare for new AES-XTS implementation Chang S. Bae
2024-03-29 1:53 ` [PATCH v9 14/14] crypto: x86/aes-kl - Implement the AES-XTS algorithm Chang S. Bae
2024-04-07 23:24 ` [PATCH v9 00/14] x86: Support Key Locker Chang S. Bae
2024-04-08 1:48 ` Eric Biggers
2024-04-15 22:16 ` Chang S. Bae
2024-04-15 22:54 ` Eric Biggers
2024-04-15 22:58 ` Chang S. Bae
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=20230410225936.8940-2-chang.seok.bae@intel.com \
--to=chang.seok.bae@intel.com \
--cc=ardb@kernel.org \
--cc=bernie.keany@intel.com \
--cc=bp@alien8.de \
--cc=bp@suse.de \
--cc=charishma1.gairuboyina@intel.com \
--cc=corbet@lwn.net \
--cc=dan.j.williams@intel.com \
--cc=dave.hansen@linux.intel.com \
--cc=dm-devel@redhat.com \
--cc=ebiggers@kernel.org \
--cc=gmazyland@gmail.com \
--cc=herbert@gondor.apana.org.au \
--cc=hpa@zytor.com \
--cc=lalithambika.krishnakumar@intel.com \
--cc=linux-crypto@vger.kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=luto@kernel.org \
--cc=mingo@kernel.org \
--cc=mingo@redhat.com \
--cc=tglx@linutronix.de \
--cc=x86@kernel.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: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).