All of lore.kernel.org
 help / color / mirror / Atom feed
From: Alison Schofield <alison.schofield@intel.com>
To: dhowells@redhat.com, tglx@linutronix.de
Cc: Kai Huang <kai.huang@intel.com>,
	Jun Nakajima <jun.nakajima@intel.com>,
	Kirill Shutemov <kirill.shutemov@intel.com>,
	Dave Hansen <dave.hansen@intel.com>,
	Jarkko Sakkinen <jarkko.sakkinen@intel.com>,
	jmorris@namei.org, keyrings@vger.kernel.org,
	linux-security-module@vger.kernel.org, mingo@redhat.com,
	hpa@zytor.com, x86@kernel.org, linux-mm@kvack.org
Subject: [RFC 01/12] docs/x86: Document the Multi-Key Total Memory Encryption API
Date: Fri, 7 Sep 2018 15:34:07 -0700	[thread overview]
Message-ID: <b9c1e3805c700043d92117462bdb6018bb9f858a.1536356108.git.alison.schofield@intel.com> (raw)
In-Reply-To: <cover.1536356108.git.alison.schofield@intel.com>

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>
---
 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.
+
+   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
+
+   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)
+
+    entropy=      ascii hex value entropy.
+                  This entropy will be used to generated the CPU key and
+		  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 
+	  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
+    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);
+
+  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);
+
-- 
2.14.1

  reply	other threads:[~2018-09-07 22:33 UTC|newest]

Thread overview: 159+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-09-07 22:23 [RFC 00/12] Multi-Key Total Memory Encryption API (MKTME) Alison Schofield
2018-09-07 22:23 ` Alison Schofield
2018-09-07 22:23 ` Alison Schofield
2018-09-07 22:34 ` Alison Schofield [this message]
2018-09-08 18:44   ` [RFC 01/12] docs/x86: Document the Multi-Key Total Memory Encryption API Randy Dunlap
2018-09-08 18:44     ` Randy Dunlap
2018-09-08 18:44     ` Randy Dunlap
2018-09-10  1:28   ` Huang, Kai
2018-09-10  1:28     ` Huang, Kai
2018-09-10  1:28     ` Huang, Kai
2018-09-11  0:13     ` Alison Schofield
2018-09-11  0:13       ` Alison Schofield
2018-09-11  0:13       ` Alison Schofield
2018-09-11  0:33       ` Huang, Kai
2018-09-11  0:33         ` Huang, Kai
2018-09-11  0:33         ` Huang, Kai
2018-09-11  0:45         ` Alison Schofield
2018-09-11  0:45           ` Alison Schofield
2018-09-11  0:45           ` Alison Schofield
2018-09-11  1:14           ` Huang, Kai
2018-09-11  1:14             ` Huang, Kai
2018-09-11  1:14             ` Huang, Kai
2018-09-11  0:14     ` Huang, Kai
2018-09-11  0:14       ` Huang, Kai
2018-09-11  0:14       ` Huang, Kai
2018-09-10 17:32   ` Sakkinen, Jarkko
2018-09-10 17:32     ` Sakkinen, Jarkko
2018-09-10 17:32     ` Sakkinen, Jarkko
2018-09-11  0:19     ` Alison Schofield
2018-09-11  0:19       ` Alison Schofield
2018-09-11  0:19       ` Alison Schofield
2018-09-07 22:34 ` [RFC 02/12] mm: Generalize the mprotect implementation to support extensions Alison Schofield
2018-09-07 22:34   ` Alison Schofield
2018-09-07 22:34   ` Alison Schofield
2018-09-10 10:12   ` Jarkko Sakkinen
2018-09-10 10:12     ` Jarkko Sakkinen
2018-09-10 10:12     ` Jarkko Sakkinen
2018-09-11  0:34     ` Alison Schofield
2018-09-11  0:34       ` Alison Schofield
2018-09-11  0:34       ` Alison Schofield
2018-09-07 22:34 ` [RFC 03/12] syscall/x86: Wire up a new system call for memory encryption keys Alison Schofield
2018-09-07 22:34   ` Alison Schofield
2018-09-07 22:34   ` Alison Schofield
2018-09-07 22:36 ` [RFC 04/12] x86/mm: Add helper functions to manage " Alison Schofield
2018-09-07 22:36   ` Alison Schofield
2018-09-07 22:36   ` Alison Schofield
2018-09-10  2:56   ` Huang, Kai
2018-09-10  2:56     ` Huang, Kai
2018-09-10  2:56     ` Huang, Kai
2018-09-10 23:37     ` Huang, Kai
2018-09-10 23:37       ` Huang, Kai
2018-09-10 23:37       ` Huang, Kai
2018-09-10 23:41       ` Alison Schofield
2018-09-10 23:41         ` Alison Schofield
2018-09-10 23:41         ` Alison Schofield
2018-09-10 17:37   ` Sakkinen, Jarkko
2018-09-07 22:36 ` [RFC 05/12] x86/mm: Add a helper function to set keyid bits in encrypted VMA's Alison Schofield
2018-09-07 22:36   ` Alison Schofield
2018-09-07 22:36   ` Alison Schofield
2018-09-10 17:57   ` Sakkinen, Jarkko
2018-09-10 17:57     ` Sakkinen, Jarkko
2018-09-10 17:57     ` Sakkinen, Jarkko
2018-09-07 22:36 ` [RFC 06/12] mm: Add the encrypt_mprotect() system call Alison Schofield
2018-09-10 18:02   ` Jarkko Sakkinen
2018-09-10 18:02     ` Jarkko Sakkinen
2018-09-10 18:02     ` Jarkko Sakkinen
2018-09-11  2:15     ` Alison Schofield
2018-09-11  2:15       ` Alison Schofield
2018-09-11  2:15       ` Alison Schofield
2018-09-07 22:37 ` [RFC 07/12] x86/mm: Add helper functions to track encrypted VMA's Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-10  3:17   ` Huang, Kai
2018-09-10  3:17     ` Huang, Kai
2018-09-07 22:37 ` [RFC 08/12] mm: Track VMA's in use for each memory encryption keyid Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-10 18:20   ` Jarkko Sakkinen
2018-09-10 18:20     ` Jarkko Sakkinen
2018-09-10 18:20     ` Jarkko Sakkinen
2018-09-11  2:39     ` Alison Schofield
2018-09-11  2:39       ` Alison Schofield
2018-09-11  2:39       ` Alison Schofield
2018-09-07 22:37 ` [RFC 09/12] mm: Restrict memory encryption to anonymous VMA's Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-07 22:37   ` Alison Schofield
2018-09-10 18:21   ` Sakkinen, Jarkko
2018-09-10 18:21     ` Sakkinen, Jarkko
2018-09-10 18:21     ` Sakkinen, Jarkko
2018-09-10 18:57     ` Dave Hansen
2018-09-10 18:57       ` Dave Hansen
2018-09-10 18:57       ` Dave Hansen
2018-09-10 21:07       ` Jarkko Sakkinen
2018-09-10 21:07         ` Jarkko Sakkinen
2018-09-10 21:07         ` Jarkko Sakkinen
2018-09-10 21:09         ` Dave Hansen
2018-09-10 21:09           ` Dave Hansen
2018-09-10 21:09           ` Dave Hansen
2018-09-07 22:38 ` [RFC 10/12] x86/pconfig: Program memory encryption keys on a system-wide basis Alison Schofield
2018-09-07 22:38   ` Alison Schofield
2018-09-07 22:38   ` Alison Schofield
2018-09-10  1:46   ` Huang, Kai
2018-09-10  1:46     ` Huang, Kai
2018-09-10 18:24   ` Sakkinen, Jarkko
2018-09-10 18:24     ` Sakkinen, Jarkko
2018-09-10 18:24     ` Sakkinen, Jarkko
2018-09-11  2:46     ` Alison Schofield
2018-09-11  2:46       ` Alison Schofield
2018-09-11  2:46       ` Alison Schofield
2018-09-11 14:31       ` Jarkko Sakkinen
2018-09-11 14:31         ` Jarkko Sakkinen
2018-09-11 14:31         ` Jarkko Sakkinen
2018-09-07 22:38 ` [RFC 11/12] keys/mktme: Add a new key service type for memory encryption keys Alison Schofield
2018-09-07 22:38   ` Alison Schofield
2018-09-07 22:38   ` Alison Schofield
2018-09-10  3:29   ` Huang, Kai
2018-09-10  3:29     ` Huang, Kai
2018-09-10  3:29     ` Huang, Kai
2018-09-10 21:47     ` Alison Schofield
2018-09-10 21:47       ` Alison Schofield
2018-09-10 21:47       ` Alison Schofield
2018-09-15  0:06     ` Alison Schofield
2018-09-15  0:06       ` Alison Schofield
2018-09-15  0:06       ` Alison Schofield
2018-09-17 10:48       ` Huang, Kai
2018-09-17 10:48         ` Huang, Kai
2018-09-17 10:48         ` Huang, Kai
2018-09-17 22:34         ` Huang, Kai
2018-09-17 22:34           ` Huang, Kai
2018-09-17 22:34           ` Huang, Kai
2018-09-07 22:39 ` [RFC 12/12] keys/mktme: Do not revoke in use " Alison Schofield
2018-09-07 22:39   ` Alison Schofield
2018-09-07 22:39   ` Alison Schofield
2018-09-10  1:10 ` [RFC 00/12] Multi-Key Total Memory Encryption API (MKTME) Huang, Kai
2018-09-10  1:10   ` Huang, Kai
2018-09-10 19:10   ` Alison Schofield
2018-09-10 19:10     ` Alison Schofield
2018-09-10 19:10     ` Alison Schofield
2018-09-11  3:15     ` Huang, Kai
2018-09-11  3:15       ` Huang, Kai
2018-09-11  3:15       ` Huang, Kai
2018-09-10 17:29 ` Sakkinen, Jarkko
2018-09-10 17:29   ` Sakkinen, Jarkko
2018-09-10 17:29   ` Sakkinen, Jarkko
2018-09-11 22:03 ` [RFC 11/12] keys/mktme: Add a new key service type for memory encryption keys David Howells
2018-09-11 22:03   ` David Howells
2018-09-11 22:03   ` David Howells
2018-09-11 22:39   ` Alison Schofield
2018-09-11 22:39     ` Alison Schofield
2018-09-11 22:39     ` Alison Schofield
2018-09-11 23:01   ` David Howells
2018-09-11 23:01     ` David Howells
2018-09-11 23:01     ` David Howells
2018-09-11 22:56 ` [RFC 04/12] x86/mm: Add helper functions to manage " David Howells
2018-09-11 22:56   ` David Howells
2018-09-11 22:56   ` David Howells
2018-09-12 11:12 ` [RFC 12/12] keys/mktme: Do not revoke in use " David Howells
2018-09-12 11:12   ` David Howells
2018-09-12 11:12   ` David Howells

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=b9c1e3805c700043d92117462bdb6018bb9f858a.1536356108.git.alison.schofield@intel.com \
    --to=alison.schofield@intel.com \
    --cc=dave.hansen@intel.com \
    --cc=dhowells@redhat.com \
    --cc=hpa@zytor.com \
    --cc=jarkko.sakkinen@intel.com \
    --cc=jmorris@namei.org \
    --cc=jun.nakajima@intel.com \
    --cc=kai.huang@intel.com \
    --cc=keyrings@vger.kernel.org \
    --cc=kirill.shutemov@intel.com \
    --cc=linux-mm@kvack.org \
    --cc=linux-security-module@vger.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 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.