On 09/07/2018 03:34 PM, Alison Schofield wrote:
Document the API's used for MKTME on Intel platforms.
MKTME: Multi-KEY Total Memory Encryption
Signed-off-by: Alison Schofield <alison.schofield@intel.com>
Hi,
A few comments below...
quoted hunk
---
Documentation/x86/mktme-keys.txt | 153 +++++++++++++++++++++++++++++++++++++++
1 file changed, 153 insertions(+)
create mode 100644 Documentation/x86/mktme-keys.txt
diff --git a/Documentation/x86/mktme-keys.txt b/Documentation/x86/mktme-keys.txt
new file mode 100644
index 000000000000..2dea7acd2a17
--- /dev/null
+++ b/Documentation/x86/mktme-keys.txt
@@ -0,0 +1,153 @@
+MKTME (Multi-Key Total Memory Encryption) is a technology that allows
+memory encryption on Intel platforms. Whereas TME (Total Memory Encryption)
+allows encryption of the entire system memory using a single key, MKTME
+allows multiple encryption domains, each having their own key. The main use
+case for the feature is virtual machine isolation. The API's introduced here
+are intended to offer flexibility to work in a wide range of uses.
+
+The externally available Intel Architecture Spec:
+https://software.intel.com/sites/default/files/managed/a5/16/Multi-Key-Total-Memory-Encryption-Spec.pdf
+
+============================ API Overview ============================
+
+There are 2 MKTME specific API's that enable userspace to create and use
+the memory encryption keys:
+
+1) Kernel Key Service: MKTME Type
+
+ MKTME is a new key type added to the existing Kernel Key Services
+ to support the memory encryption keys. The MKTME service manages
+ the addition and removal of MKTME keys. It maps userspace keys
+ to hardware keyids and programs the hardware with user requested
+ encryption parameters.
+
+ o An understanding of the Kernel Key Service is required in order
+ to use the MKTME key type as it is a subset of that service.
reference available?
quoted hunk
+
+ o MKTME keys are a limited resource. There is a single pool of
+ MKTME keys for a system and that pool can be from 3 to 63 keys.
+ With that in mind, userspace may take advantage of the kernel
+ key services sharing and permissions model for userspace keys.
+ One key can be shared as long as each user has the permission
+ of "KEY_NEED_VIEW" to use it.
+
+ o MKTME key type uses capabilities to restrict the allocation
+ of keys. It only requires CAP_SYS_RESOURCE, but will accept
+ the broader capability of CAP_SYS_ADMIN. See capabilities(7).
+
+ o The MKTME key service blocks kernel key service commands that
+ could lead to reprogramming of in use keys, or loss of keys from
+ the pool. This means MKTME does not allow a key to be invalidated,
+ unlinked, or timed out. These operations are blocked by MKTME as
+ it creates all keys with the internal flag KEY_FLAG_KEEP.
+
+ o MKTME does not support the keyctl option of UPDATE. Userspace
+ may change the programming of a key by revoking it and adding
+ a new key with the updated encryption options (or vice-versa).
+
+2) System Call: encrypt_mprotect()
+
+ MKTME encryption is requested by calling encrypt_mprotect(). The
+ caller passes the serial number to a previously allocated and
+ programmed encryption key. That handle was created with the MKTME
+ Key Service.
+
+ o The caller must have KEY_NEED_VIEW permission on the key
key.
quoted hunk
+
+ o The range of memory that is to be protected must be mapped as
+ ANONYMOUS. If it is not, the entire encrypt_mprotect() request
+ fails with EINVAL.
+
+ o As an extension to the existing mprotect() system call,
+ encrypt_mprotect() supports the legacy mprotect behavior plus
+ the enabling of memory encryption. That means that in addition
+ to encrypting the memory, the protection flags will be updated
+ as requested in the call.
+
+ o Additional mprotect() calls to memory already protected with
+ MKTME will not alter the MKTME status.
+
+====================== Usage: MKTME Key Service ======================
+
+MKTME is enabled on supported Intel platforms by selecting
+CONFIG_X86_INTEL_MKTME which selects CONFIG_MKTME_KEYS.
+
+Allocating MKTME Keys via command line or system call:
+ keyctl add mktme name "[options]" ring
+
+ key_serial_t add_key(const char *type, const char *description,
+ const void *payload, size_t plen,
+ key_serial_t keyring);
+
+Revoking MKTME Keys via command line or system call::
+ keyctl revoke <key>
+
+ long keyctl(KEYCTL_REVOKE, key_serial_t key);
+
+Options Field Definition:
+ userkey= ASCII HEX value encryption key. Defaults to a CPU
+ generated key if a userkey is not defined here.
+
+ algorithm= Encryption algorithm name as a string.
+ Valid algorithm: "aes-xts-128"
+
+ tweak= ASCII HEX value tweak key. Tweak key will be added to the
+ userkey... (need to be clear here that this is being sent
+ to the hardware - kernel not messing w it)
with it)
+
+ entropy= ascii hex value entropy.
ASCII
+ This entropy will be used to generated the CPU key and
to generate the
quoted hunk
+ the tweak key when CPU generated key is requested.
+
+Algorithm Dependencies:
+ AES-XTS 128 is the only supported algorithm.
+ There are only 2 ways that AES-XTS 128 may be used:
+
+ 1) User specified encryption key
+ - The user specified encryption key must be exactly
+ 16 ASCII Hex bytes (128 bits).
+ - A tweak key must be specified and it must be exactly
+ 16 ASCII Hex bytes (128 bits).
+ - No entropy field is accepted.
+
+ 2) CPU generated encryption key
+ - When no user specified encryption key is provided, the
+ default encryption key will be CPU generated.
+ - User must specify 16 ASCII Hex bytes of entropy. This
above line ends with a space. Please drop it.
quoted hunk
+ entropy will be used by the CPU to generate both the
+ encryption key and the tweak key.
+ - No entropy field is accepted.
+
+====================== Usage: encrypt_mprotect() ======================
+
+System Call encrypt_mprotect()::
+
+ This system call is an extension of the existing mprotect() system
+ call. It requires the same parameters as legary mprotect() plus
legacy
quoted hunk
+ one additional parameter, the keyid. Userspace must provide the
+ key serial number assigned through the kernel key service.
+
+ int encrypt_mprotect(void *addr, size_t len, int prot, int keyid);
+
+====================== Usage: Sample Roundtrip ======================
+
+Sample usage of MKTME Key Service API with encrypt_mprotect() API:
+
+ Add a key:
+ key = add_key(mktme, name, options, strlen(option), keyring);
strlen(options),
quoted hunk
+
+ Map memory:
+ ptr = mmap(NULL, size, prot, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
+
+ Protect memory:
+ ret = syscall(sys_encrypt_mprotect, ptr, size, prot, keyid);
+
+ Use protected memory:
+ ................
+
+ Free memory:
+ ret = munmap(ptr, size);
+
+ Revoke key:
+ ret = keyctl(KEYCTL_REVOKE, key);
+
--
~Randy