| Message ID | 20240329015346.635933-2-chang.seok.bae@intel.com (mailing list archive) |
|---|---|
| State | Deferred |
| Delegated to: | Herbert Xu |
| Headers | show |
| Series | x86: Support Key Locker | expand |
Hi, On 3/28/24 18:53, Chang S. Bae wrote: > 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> > Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com> > Cc: Randy Dunlap <rdunlap@infradead.org> > --- > Changes from v8: > * Change wording of documentation slightly. (Randy Dunlap and Bagas > Sanjaya) > > Changes from v6: > * Rebase on the upstream -- commit ff61f0791ce9 ("docs: move x86 > documentation into Documentation/arch/"). (Nathan Huckleberry) > * Remove a duplicated sentence -- 'But there is no AES-KL instruction > to process a 192-bit key.' > * Update the text for clarity and readability: > - Clarify the error code and exemplify the backup failure > - Use 'wrapping key' instead of less readable 'IWKey' > > 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/arch/x86/keylocker.html > --- > Documentation/arch/x86/index.rst | 1 + > Documentation/arch/x86/keylocker.rst | 96 ++++++++++++++++++++++++++++ > 2 files changed, 97 insertions(+) > create mode 100644 Documentation/arch/x86/keylocker.rst > > diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst > index 8ac64d7de4dc..669c239c009f 100644 > --- a/Documentation/arch/x86/index.rst > +++ b/Documentation/arch/x86/index.rst > @@ -43,3 +43,4 @@ x86-specific Documentation > features > elf_auxvec > xstate > + keylocker > diff --git a/Documentation/arch/x86/keylocker.rst b/Documentation/arch/x86/keylocker.rst > new file mode 100644 > index 000000000000..b28addb8eaf4 > --- /dev/null > +++ b/Documentation/arch/x86/keylocker.rst > @@ -0,0 +1,96 @@ > +.. 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. > + > +CPU-internal Wrapping Key > +========================= > + > +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: > + > +Wrapping Key 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. > + > +Upon the event of a wrapping key restore failure upon resume from suspend, > +all established key handles become invalid. In flight dm-crypt operations In-flight > +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 or reboot. If the volume > +impacted by a wrapping key 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 wrapping key 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 wrapping key state, but the > +architecture does not provide that. An emulation of that capability, by > +caching per-VM wrapping keys 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 -EINVAL. > + Note that this flag is also set if the wrapping key is changed, e.g., > + because of the backup error. > + > +* AES-KL implements support for 128-bit and 256-bit keys, but there is no > + AES-KL instruction to process an 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. Reviewed-by: Randy Dunlap <rdunlap@infradead.org> thanks.
diff --git a/Documentation/arch/x86/index.rst b/Documentation/arch/x86/index.rst index 8ac64d7de4dc..669c239c009f 100644 --- a/Documentation/arch/x86/index.rst +++ b/Documentation/arch/x86/index.rst @@ -43,3 +43,4 @@ x86-specific Documentation features elf_auxvec xstate + keylocker diff --git a/Documentation/arch/x86/keylocker.rst b/Documentation/arch/x86/keylocker.rst new file mode 100644 index 000000000000..b28addb8eaf4 --- /dev/null +++ b/Documentation/arch/x86/keylocker.rst @@ -0,0 +1,96 @@ +.. 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. + +CPU-internal Wrapping Key +========================= + +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: + +Wrapping Key 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. + +Upon the event of a wrapping key 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 or reboot. If the volume +impacted by a wrapping key 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 wrapping key 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 wrapping key state, but the +architecture does not provide that. An emulation of that capability, by +caching per-VM wrapping keys 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 -EINVAL. + Note that this flag is also set if the wrapping key is changed, e.g., + because of the backup error. + +* AES-KL implements support for 128-bit and 256-bit keys, but there is no + AES-KL instruction to process an 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.