lkml.org 
[lkml]   [2023]   [Apr]   [10]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    Patch in this message
    /
    From
    Subject[PATCH v6 01/12] Documentation/x86: Document Key Locker
    Date
    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
    \
     
     \ /
      Last update: 2023-04-11 01:13    [W:4.025 / U:0.040 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site