From: rdunlap@infradead.org (Randy Dunlap)
To: linux-security-module@vger.kernel.org
Subject: [RFC 01/12] docs/x86: Document the Multi-Key Total Memory Encryption API
Date: Sat, 8 Sep 2018 11:44:19 -0700 [thread overview]
Message-ID: <b821cd4c-b061-3ea0-b0af-992d844ddad5@infradead.org> (raw)
In-Reply-To: <b9c1e3805c700043d92117462bdb6018bb9f858a.1536356108.git.alison.schofield@intel.com>
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...
> ---
> 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?
> +
> + 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.
> +
> + 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
> + 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.
> + 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
> + 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),
> +
> + 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
next prev parent reply other threads:[~2018-09-08 18:44 UTC|newest]
Thread overview: 53+ 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:34 ` [RFC 02/12] mm: Generalize the mprotect implementation to support extensions Alison Schofield
2018-09-10 10:12 ` Jarkko Sakkinen
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:36 ` [RFC 04/12] x86/mm: Add helper functions to manage " Alison Schofield
2018-09-10 2:56 ` Huang, Kai
2018-09-10 23:37 ` Huang, Kai
2018-09-10 23:41 ` Alison Schofield
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-10 17:57 ` Sakkinen, Jarkko
2018-09-07 22:37 ` [RFC 07/12] x86/mm: Add helper functions to track " Alison Schofield
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-10 18:20 ` Jarkko Sakkinen
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-10 18:21 ` Sakkinen, Jarkko
2018-09-10 18:57 ` Dave Hansen
2018-09-10 21:07 ` Jarkko Sakkinen
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-10 1:46 ` Huang, Kai
2018-09-10 18:24 ` Sakkinen, Jarkko
2018-09-11 2:46 ` Alison Schofield
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-10 3:29 ` Huang, Kai
2018-09-10 21:47 ` Alison Schofield
2018-09-15 0:06 ` Alison Schofield
2018-09-17 10:48 ` 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-10 1:10 ` [RFC 00/12] Multi-Key Total Memory Encryption API (MKTME) Huang, Kai
2018-09-10 19:10 ` Alison Schofield
2018-09-11 3:15 ` Huang, Kai
2018-09-10 17:29 ` Sakkinen, Jarkko
[not found] ` <b9c1e3805c700043d92117462bdb6018bb9f858a.1536356108.git.alison.schofield@intel.com>
2018-09-08 18:44 ` Randy Dunlap [this message]
2018-09-10 1:28 ` [RFC 01/12] docs/x86: Document the Multi-Key Total Memory Encryption API Huang, Kai
2018-09-11 0:13 ` Alison Schofield
2018-09-11 0:33 ` Huang, Kai
2018-09-11 0:45 ` Alison Schofield
2018-09-11 1:14 ` Huang, Kai
2018-09-11 0:14 ` Huang, Kai
2018-09-10 17:32 ` Sakkinen, Jarkko
2018-09-11 0:19 ` Alison Schofield
[not found] ` <7d27511b07c8337e15096214622b66ef8f0fa345.1536356108.git.alison.schofield@intel.com>
2018-09-10 18:02 ` [RFC 06/12] mm: Add the encrypt_mprotect() system call Jarkko Sakkinen
2018-09-11 2:15 ` Alison Schofield
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:39 ` Alison Schofield
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-12 11:12 ` [RFC 12/12] keys/mktme: Do not revoke in use " 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=b821cd4c-b061-3ea0-b0af-992d844ddad5@infradead.org \
--to=rdunlap@infradead.org \
--cc=linux-security-module@vger.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).