| Message ID | c2276bbbb19f3a28bd37c3dd6b1021e2d9a10916.1543903910.git.alison.schofield@intel.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | Multi-Key Total Memory Encryption API (MKTME) | expand |
> On Dec 3, 2018, at 11:39 PM, Alison Schofield <alison.schofield@intel.com> wrote: I realize you’re writing code to expose hardware behavior, but I’m not sure this really makes sense in this context. > . > + > +Usage > +----- > + When using the Kernel Key Service to request an *mktme* key, > + specify the *payload* as follows: > + > + type= > + *user* User will supply the encryption key data. Use this > + type to directly program a hardware encryption key. > + I think that “user” probably sense as a “key service” key, but I don’t think it is at all useful for non-persistent memory. Even if we take for granted that MKTME for anonymous memory is useful at all, “cpu” seems to be better in all respects. Perhaps support for “user” should be tabled until there’s a design for how to use this for pmem? I imagine it would look quite a bit like dm-crypt. Advanced pmem filesystems could plausibly use different keys for different files, I suppose. If “user” is dropped, I think a lot of the complexity goes away. Hotplug becomes automatic, right? > + *cpu* User requests a CPU generated encryption key. Okay, maybe, but it’s still unclear to me exactly what the intended benefit is, though. > + The CPU generates and assigns an ephemeral key. > + > + *clear* User requests that a hardware encryption key be > + cleared. This will clear the encryption key from > + the hardware. On execution this hardware key gets > + TME behavior. > + Why is this a key type? Shouldn’t the API to select a key just have an option to ask for no key to be used? > + *no-encrypt* > + User requests that hardware does not encrypt > + memory when this key is in use. Same as above. If there’s a performance benefit, then there could be a way to ask for cleartext memory. Similarly, some pmem users may want a way to keep their pmem unencrypted. —Andy
On Wed, Dec 05, 2018 at 10:11:18AM -0800, Andy Lutomirski wrote: > > > > On Dec 3, 2018, at 11:39 PM, Alison Schofield <alison.schofield@intel.com> wrote: > > I realize you’re writing code to expose hardware behavior, but I’m not sure this > really makes sense in this context. Your observation is accurate. The Usage defined here is very closely aligned to the Intel MKTME Architecture spec. That's a starting point, but not the ending point. We need to implement the feature set that makes sense. More below... > > + > > + type= > > + *user* User will supply the encryption key data. Use this > > + type to directly program a hardware encryption key. > > + > > I think that “user” probably sense as a “key service” key, but I don’t think it is at all useful for non-persistent memory. Even if we take for granted that MKTME for anonymous memory is useful at all, “cpu” seems to be better in all respects. > > > Perhaps support for “user” should be tabled until there’s a design for how to use this for pmem? I imagine it would look quite a bit like dm-crypt. Advanced pmem filesystems could plausibly use different keys for different files, I suppose. > > If “user” is dropped, I think a lot of the complexity goes away. Hotplug becomes automatic, right? Dropping 'user' type removes a great deal of complexity. Let me follow up in 2 ways: 1) Find out when MKTME support for pmem is required. 2) Go back to the the requirements and get the justification for user type. > > > + *cpu* User requests a CPU generated encryption key. > > Okay, maybe, but it’s still unclear to me exactly what the intended benefit is, though. *cpu* is the RANDOM key generated by the cpu. If there were no other options, then this would be default, and go away. > > + *clear* User requests that a hardware encryption key be > > + cleared. This will clear the encryption key from > > + the hardware. On execution this hardware key gets > > + TME behavior. > > + > > Why is this a key type? Shouldn’t the API to select a key just have an option to ask for no key to be used? The *clear* key has been requested in order to clear/erase the users key data that has been programmed into a hardware slot. User does not want to leave a slot programmed with their encryption data when they are done with it. > > + *no-encrypt* > > + User requests that hardware does not encrypt > > + memory when this key is in use. > > Same as above. If there’s a performance benefit, then there could be a way to ask for cleartext memory. Similarly, some pmem users may want a way to keep their pmem unencrypted. So, this is the way to ask for cleartext memory. The entire system will be encrypted with the system wide TME Key. A subset of that will be protected with MKTME Keys. If user wants, no encrypt, this *no-encrypt* is the way to do it. Alison > > —Andy
>> On Dec 5, 2018, at 11:22 AM, Alison Schofield <alison.schofield@intel.com> wrote: >> >> On Wed, Dec 05, 2018 at 10:11:18AM -0800, Andy Lutomirski wrote: >> >> >>> On Dec 3, 2018, at 11:39 PM, Alison Schofield <alison.schofield@intel.com> wrote: >> >> I realize you’re writing code to expose hardware behavior, but I’m not sure this >> really makes sense in this context. > > Your observation is accurate. The Usage defined here is very closely > aligned to the Intel MKTME Architecture spec. That's a starting point, > but not the ending point. We need to implement the feature set that > makes sense. More below... > >>> + >>> + type= >>> + *user* User will supply the encryption key data. Use this >>> + type to directly program a hardware encryption key. >>> + >> >> I think that “user” probably sense as a “key service” key, but I don’t think it is at all useful for non-persistent memory. Even if we take for granted that MKTME for anonymous memory is useful at all, “cpu” seems to be better in all respects. >> >> >> Perhaps support for “user” should be tabled until there’s a design for how to use this for pmem? I imagine it would look quite a bit like dm-crypt. Advanced pmem filesystems could plausibly use different keys for different files, I suppose. >> >> If “user” is dropped, I think a lot of the complexity goes away. Hotplug becomes automatic, right? > > Dropping 'user' type removes a great deal of complexity. > > Let me follow up in 2 ways: > 1) Find out when MKTME support for pmem is required. > 2) Go back to the the requirements and get the justification for user > type. > >> >>> + *cpu* User requests a CPU generated encryption key. >> >> Okay, maybe, but it’s still unclear to me exactly what the intended benefit is, though. > *cpu* is the RANDOM key generated by the cpu. If there were no other > options, then this would be default, and go away. > >>> + *clear* User requests that a hardware encryption key be >>> + cleared. This will clear the encryption key from >>> + the hardware. On execution this hardware key gets >>> + TME behavior. >>> + >> >> Why is this a key type? Shouldn’t the API to select a key just have an option to ask for no key to be used? > > The *clear* key has been requested in order to clear/erase the users > key data that has been programmed into a hardware slot. User does not > want to leave a slot programmed with their encryption data when they > are done with it. Can’t you just clear the key when the key is deleted by the user? Asking the user to allocate a *new* key and hope that it somehow ends up in the same spot seems like a poor design, especially if future hardware gains support for key slot virtualization in some way that makes the slot allocation more dynamic. > >>> + *no-encrypt* >>> + User requests that hardware does not encrypt >>> + memory when this key is in use. >> >> Same as above. If there’s a performance benefit, then there could be a way to ask for cleartext memory. Similarly, some pmem users may want a way to keep their pmem unencrypted. > > So, this is the way to ask for cleartext memory. > The entire system will be encrypted with the system wide TME Key. > A subset of that will be protected with MKTME Keys. > If user wants, no encrypt, this *no-encrypt* is the way to do it. > Understood. I’m saying that having a *key* (in the add_key sense) for it seems unnecessary. Whatever the final API for controlling the use of keys, adding an option to ask for clear text seems reasonable. This actually seems more useful for anonymous memory than the cpu-generates keys are IMO. I do think that, before you invest too much time in perfecting the series with the current design, you should identify the use cases, make sure the use cases are valid, and figure out whether your API design is appropriate. After considerable head-scratching, I haven’t thought of a reason that explicit CPU generated keys are any better than the default TME key, at least in the absence of additional hardware support for locking down what code can use what key. The sole exception is that a key can be removed, which is probably faster than directly zeroing large amounts of data. I understand that it would be very nice to say "hey, cloud customer, your VM has all its memory encrypted with a key that is unique to your VM", but that seems to be more or less just a platitude with no actual effect. Anyone who snoops the memory bus or steals a DIMM learns nothing unless they also take control of the CPU and can replay all the data into the CPU. On the other hand, anyone who can get the CPU to read from a given physical address (which seems like the most likely threat) can just get the CPU to decrypt any tenant's data. So, for example, if someone manages to write a couple of words to the EPT for one VM, then they can easily read another VM's data, MKTME or no MKTME, because the memory controller has no clue which VM initiated the access. I suppose there's some smallish value in rotating the key every now and then to make old data non-replayable, but an attack that compromises the memory bus and only later compromises the CPU is a strange threat model.
I'll focus my remarks now towards documentation as I have lots of catching up to do with TME :-) I'll give more feedback of actual code changes once v18 of the SGX patch set is out, pull request for TPM 4.21 changes is out and maybe a new version of this patch set has been released. Right now too much on my shoulders to go too deep with this patch set. On Mon, 2018-12-03 at 23:39 -0800, Alison Schofield wrote: > This includes an overview, a section on each API: MTKME Keys and > system call encrypt_mprotect(), and a demonstration program. > > (Some of this info is destined for man pages.) > > Change-Id: I34dc9ff1a1308c057ec4bb3e652c4d7ce6995606 > Signed-off-by: Alison Schofield <alison.schofield@intel.com> Co-developed-by: Kirill A. Shutemov <kirill.shutemov@linux.intel.com> ? Not needed if this is for the most part written by you. > Signed-off-by: Kirill A. Shutemov <kirill.shutemov@linux.intel.com> > --- > Documentation/x86/mktme/index.rst | 11 +++ > Documentation/x86/mktme/mktme_demo.rst | 53 ++++++++++++++ > Documentation/x86/mktme/mktme_encrypt.rst | 58 +++++++++++++++ > Documentation/x86/mktme/mktme_keys.rst | 109 > +++++++++++++++++++++++++++++ > Documentation/x86/mktme/mktme_overview.rst | 60 ++++++++++++++++ > 5 files changed, 291 insertions(+) > create mode 100644 Documentation/x86/mktme/index.rst > create mode 100644 Documentation/x86/mktme/mktme_demo.rst > create mode 100644 Documentation/x86/mktme/mktme_encrypt.rst > create mode 100644 Documentation/x86/mktme/mktme_keys.rst > create mode 100644 Documentation/x86/mktme/mktme_overview.rst > > diff --git a/Documentation/x86/mktme/index.rst > b/Documentation/x86/mktme/index.rst > new file mode 100644 > index 000000000000..8c556d04cbc4 > --- /dev/null > +++ b/Documentation/x86/mktme/index.rst > @@ -0,0 +1,11 @@ > + SPDX? > +============================================= > +Multi-Key Total Memory Encryption (MKTME) API > +============================================= > + > +.. toctree:: > + > + mktme_overview > + mktme_keys > + mktme_encrypt > + mktme_demo > diff --git a/Documentation/x86/mktme/mktme_demo.rst > b/Documentation/x86/mktme/mktme_demo.rst > new file mode 100644 > index 000000000000..afd50772e65d > --- /dev/null > +++ b/Documentation/x86/mktme/mktme_demo.rst > @@ -0,0 +1,53 @@ > +Demonstration Program using MKTME API's > +======================================= Probably would be better idea to put into tools/testings/selftest/x86 and not as part of the documentation. > + > +/* Compile with the keyutils library: cc -o mdemo mdemo.c -lkeyutils */ > + > +#include <sys/mman.h> > +#include <sys/syscall.h> > +#include <sys/types.h> > +#include <keyutils.h> > +#include <stdio.h> > +#include <string.h> > +#include <unistd.h> > + > +#define PAGE_SIZE sysconf(_SC_PAGE_SIZE) > +#define sys_encrypt_mprotect 335 > + > +void main(void) > +{ > + char *options_CPU = "algorithm=aes-xts-128 type=cpu"; > + long size = PAGE_SIZE; > + key_serial_t key; > + void *ptra; > + int ret; > + > + /* Allocate an MKTME Key */ > + key = add_key("mktme", "testkey", options_CPU, strlen(options_CPU), > + KEY_SPEC_THREAD_KEYRING); > + > + if (key == -1) { > + printf("addkey FAILED\n"); > + return; > + } > + /* Map a page of ANONYMOUS memory */ > + ptra = mmap(NULL, size, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); > + if (!ptra) { > + printf("failed to mmap"); > + goto inval_key; > + } > + /* Encrypt that page of memory with the MKTME Key */ > + ret = syscall(sys_encrypt_mprotect, ptra, size, PROT_NONE, key); > + if (ret) > + printf("mprotect error [%d]\n", ret); > + > + /* Enjoy that page of encrypted memory */ > + > + /* Free the memory */ > + ret = munmap(ptra, size); > + > +inval_key: > + /* Free the Key */ > + if (keyctl(KEYCTL_INVALIDATE, key) == -1) > + printf("invalidate failed on key [%d]\n", key); Would it make sense to print error messages to stderr? > +} > diff --git a/Documentation/x86/mktme/mktme_encrypt.rst > b/Documentation/x86/mktme/mktme_encrypt.rst > new file mode 100644 > index 000000000000..ede5237183fc > --- /dev/null > +++ b/Documentation/x86/mktme/mktme_encrypt.rst > @@ -0,0 +1,58 @@ > +MKTME API: system call encrypt_mprotect() > +========================================= > + > +Synopsis > +-------- > +int encrypt_mprotect(void \*addr, size_t len, int prot, key_serial_t serial); > + > +Where *key_serial_t serial* is the serial number of a key allocated > +using the MKTME Key Service. There is only one key service i.e. the kernel keyring. Should be rephrased somehow. > + > +Description > +----------- > + encrypt_mprotect() encrypts the memory pages containing any part > + of the address range in the interval specified by addr and len. What does it actually do? I don't think the syscall does any encryption, does it? I'm not looking SDM level details but somehow better description what does it do would be nice. > + > + 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. Ditto. > + > + The *addr* and *len* must be aligned to a page boundary. > + > + The caller must have *KEY_NEED_VIEW* permission on the key. Maybe more verbose description, especially when it is a must. > + > + The range of memory that is to be protected must be mapped as > + *ANONYMOUS*. Ditto. > + > +Errors > +------ > + In addition to the Errors returned from legacy mprotect() > + encrypt_mprotect will return: > + > + ENOKEY *serial* parameter does not represent a valid key. > + > + EINVAL *len* parameter is not page aligned. > + > + EACCES Caller does not have *KEY_NEED_VIEW* permission on the key. > + > +EXAMPLE > +-------- > + Allocate an MKTME Key:: > + serial = add_key("mktme", "name", "type=cpu algorithm=aes-xts-128" @u > + > + Map ANONYMOUS memory:: > + ptr = mmap(NULL, size, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); > + > + Protect memory:: > + ret = syscall(SYS_encrypt_mprotect, ptr, size, PROT_READ|PROT_WRITE, > + serial); > + > + Use the encrypted memory > + > + Free memory:: > + ret = munmap(ptr, size); > + > + Free the key resource:: > + ret = keyctl(KEYCTL_INVALIDATE, serial); > + Not really sure what this example serves as you already had an example program... Have you read pkeys man page? It has really good balance explaining how it is implemented and used (man pkeys, not man pkey_mprotect()). What if you suddenly change a key for VMA? I guess memory is then corrupted? Not documented here. Should be. I did not find the thing I was looking for most i.e. some high level description of the threat model. Emphasis on high-level as kernel documentation is not a CVE database. > diff --git a/Documentation/x86/mktme/mktme_keys.rst > b/Documentation/x86/mktme/mktme_keys.rst > new file mode 100644 > index 000000000000..5837909b2c54 > --- /dev/null > +++ b/Documentation/x86/mktme/mktme_keys.rst > @@ -0,0 +1,109 @@ > +MKTME Key Service API > +===================== > +MKTME is a new key service type added to the Linux Kernel Key Service. > + > +The MKTME Key Service type is available when CONFIG_X86_INTEL_MKTME is > +turned on in Intel platforms that support the MKTME feature. > + > +The MKTME Key Service type manages the allocation of hardware encryption > +keys. Users can request an MKTME type key and then use that key to > +encrypt memory with the encrypt_mprotect() system call. > + > +Usage > +----- > + When using the Kernel Key Service to request an *mktme* key, > + specify the *payload* as follows: > + > + type= > + *user* User will supply the encryption key data. Use this > + type to directly program a hardware encryption key. > + > + *cpu* User requests a CPU generated encryption key. > + The CPU generates and assigns an ephemeral key. How are these implemented? Is there an opcode to request CPU to generate a key, or? What about the user key? Does cpu key ever leave out of the CPU package? The user key sounds like a really bad idea at the first sight and maybe should be considered to be left out. What would be a legit use case for it? Are the keys per-process or is it a global resource? > + *clear* User requests that a hardware encryption key be > + cleared. This will clear the encryption key from > + the hardware. On execution this hardware key gets > + TME behavior. > + > + *no-encrypt* > + User requests that hardware does not encrypt > + memory when this key is in use. Not sure about these with my current knowledge. > + > + algorithm= > + When type=user or type=cpu the algorithm field must be > + *aes-xts-128* > + > + When type=clear or type=no-encrypt the algorithm field > + must not be present in the payload. This parameter must be removed as it is a function of other paramaters and nothing else i.e. complexity without gain. > + This document does not intend to document KKS, but only the > + MKTME type of the KKS. The options of the KKS can be grouped > + into 2 classes for purposes of understanding how MKTME operates > + within the broader KKS. Maybe just delete this paragraph? I think it is just stating the obvious. I think you need this paragraph only because you have deployed this document to wrong place. Better path would be Documentation/security/keys/mktme.rst. /Jarkko
diff --git a/Documentation/x86/mktme/index.rst b/Documentation/x86/mktme/index.rst new file mode 100644 index 000000000000..8c556d04cbc4 --- /dev/null +++ b/Documentation/x86/mktme/index.rst @@ -0,0 +1,11 @@ + +============================================= +Multi-Key Total Memory Encryption (MKTME) API +============================================= + +.. toctree:: + + mktme_overview + mktme_keys + mktme_encrypt + mktme_demo diff --git a/Documentation/x86/mktme/mktme_demo.rst b/Documentation/x86/mktme/mktme_demo.rst new file mode 100644 index 000000000000..afd50772e65d --- /dev/null +++ b/Documentation/x86/mktme/mktme_demo.rst @@ -0,0 +1,53 @@ +Demonstration Program using MKTME API's +======================================= + +/* Compile with the keyutils library: cc -o mdemo mdemo.c -lkeyutils */ + +#include <sys/mman.h> +#include <sys/syscall.h> +#include <sys/types.h> +#include <keyutils.h> +#include <stdio.h> +#include <string.h> +#include <unistd.h> + +#define PAGE_SIZE sysconf(_SC_PAGE_SIZE) +#define sys_encrypt_mprotect 335 + +void main(void) +{ + char *options_CPU = "algorithm=aes-xts-128 type=cpu"; + long size = PAGE_SIZE; + key_serial_t key; + void *ptra; + int ret; + + /* Allocate an MKTME Key */ + key = add_key("mktme", "testkey", options_CPU, strlen(options_CPU), + KEY_SPEC_THREAD_KEYRING); + + if (key == -1) { + printf("addkey FAILED\n"); + return; + } + /* Map a page of ANONYMOUS memory */ + ptra = mmap(NULL, size, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); + if (!ptra) { + printf("failed to mmap"); + goto inval_key; + } + /* Encrypt that page of memory with the MKTME Key */ + ret = syscall(sys_encrypt_mprotect, ptra, size, PROT_NONE, key); + if (ret) + printf("mprotect error [%d]\n", ret); + + /* Enjoy that page of encrypted memory */ + + /* Free the memory */ + ret = munmap(ptra, size); + +inval_key: + /* Free the Key */ + if (keyctl(KEYCTL_INVALIDATE, key) == -1) + printf("invalidate failed on key [%d]\n", key); +} diff --git a/Documentation/x86/mktme/mktme_encrypt.rst b/Documentation/x86/mktme/mktme_encrypt.rst new file mode 100644 index 000000000000..ede5237183fc --- /dev/null +++ b/Documentation/x86/mktme/mktme_encrypt.rst @@ -0,0 +1,58 @@ +MKTME API: system call encrypt_mprotect() +========================================= + +Synopsis +-------- +int encrypt_mprotect(void \*addr, size_t len, int prot, key_serial_t serial); + +Where *key_serial_t serial* is the serial number of a key allocated +using the MKTME Key Service. + +Description +----------- + encrypt_mprotect() encrypts the memory pages containing any part + of the address range in the interval specified by addr and len. + + 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. + + The *addr* and *len* must be aligned to a page boundary. + + The caller must have *KEY_NEED_VIEW* permission on the key. + + The range of memory that is to be protected must be mapped as + *ANONYMOUS*. + +Errors +------ + In addition to the Errors returned from legacy mprotect() + encrypt_mprotect will return: + + ENOKEY *serial* parameter does not represent a valid key. + + EINVAL *len* parameter is not page aligned. + + EACCES Caller does not have *KEY_NEED_VIEW* permission on the key. + +EXAMPLE +-------- + Allocate an MKTME Key:: + serial = add_key("mktme", "name", "type=cpu algorithm=aes-xts-128" @u + + Map ANONYMOUS memory:: + ptr = mmap(NULL, size, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); + + Protect memory:: + ret = syscall(SYS_encrypt_mprotect, ptr, size, PROT_READ|PROT_WRITE, + serial); + + Use the encrypted memory + + Free memory:: + ret = munmap(ptr, size); + + Free the key resource:: + ret = keyctl(KEYCTL_INVALIDATE, serial); + diff --git a/Documentation/x86/mktme/mktme_keys.rst b/Documentation/x86/mktme/mktme_keys.rst new file mode 100644 index 000000000000..5837909b2c54 --- /dev/null +++ b/Documentation/x86/mktme/mktme_keys.rst @@ -0,0 +1,109 @@ +MKTME Key Service API +===================== +MKTME is a new key service type added to the Linux Kernel Key Service. + +The MKTME Key Service type is available when CONFIG_X86_INTEL_MKTME is +turned on in Intel platforms that support the MKTME feature. + +The MKTME Key Service type manages the allocation of hardware encryption +keys. Users can request an MKTME type key and then use that key to +encrypt memory with the encrypt_mprotect() system call. + +Usage +----- + When using the Kernel Key Service to request an *mktme* key, + specify the *payload* as follows: + + type= + *user* User will supply the encryption key data. Use this + type to directly program a hardware encryption key. + + *cpu* User requests a CPU generated encryption key. + The CPU generates and assigns an ephemeral key. + + *clear* User requests that a hardware encryption key be + cleared. This will clear the encryption key from + the hardware. On execution this hardware key gets + TME behavior. + + *no-encrypt* + User requests that hardware does not encrypt + memory when this key is in use. + + algorithm= + When type=user or type=cpu the algorithm field must be + *aes-xts-128* + + When type=clear or type=no-encrypt the algorithm field + must not be present in the payload. + + key= + When type=user the user must supply a 128 bit encryption + key as exactly 32 ASCII hexadecimal characters. + + When type=cpu the user may optionally supply 128 bits of + entropy for the CPU generated encryption key in this field. + It must be exactly 32 ASCII hexadecimal characters. + + When type=clear or type=no-encrypt this key field must + not be present in the payload. + + tweak= + When type=user the user must supply a 128 bit tweak key + as exactly 32 ASCII hexadecimal characters. + + When type=cpu the user may optionally supply 128 bits of + entropy for the CPU generated tweak key in this field. It + must be exactly 32 ASCII hexadecimal characters. + + When type=clear or type=no-encrypt the tweak field must + not be present in the payload. + +ERRORS +------ + In addition to the Errors returned from the Kernel Key Service, + add_key(2) or keyctl(1) commands, the MKTME Key Service type may + return the following errors: + + EINVAL for any payload specification that does not match the + MKTME type payload as defined above. + EACCES for access denied. MKTME key type uses capabilities to + restrict the allocation of keys. CAP_SYS_RESOURCE is + required, but it will accept the broader capability of + CAP_SYS_ADMIN. See capabilities(7). + + ENOKEY if a hardware key cannot be allocated. Additional error + messages will describe the hardware programming errors. + +EXAMPLES +-------- + Add a 'user' type key:: + + char \*options_USER = "type=user + algorithm=aes-xts-128 + key=12345678912345671234567891234567 + tweak=12345678912345671234567891234567"; + + key = add_key("mktme", "name", options_USER, strlen(options_USER), + KEY_SPEC_THREAD_KEYRING); + + Add a 'cpu' type key:: + + char \*options_USER = "type=cpu algorithm=aes-xts-128"; + + key = add_key("mktme", "name", options_CPU, strlen(options_CPU), + KEY_SPEC_THREAD_KEYRING); + + Update a key to 'Clear' type:: + + Note: This has the effect of clearing out the previously programmed + encryption data in the hardware. Use this to clear the hardware slot + prior to invalidating the key. + + ret = keyctl(KEYCTL_UPDATE, key, "type=clear", strlen(options_CLEAR); + + Add a "no-encrypt' type key:: + + key = add_key("mktme", "name", "no-encrypt", strlen(options_CPU), + KEY_SPEC_THREAD_KEYRING); + diff --git a/Documentation/x86/mktme/mktme_overview.rst b/Documentation/x86/mktme/mktme_overview.rst new file mode 100644 index 000000000000..cc2c4a8320e7 --- /dev/null +++ b/Documentation/x86/mktme/mktme_overview.rst @@ -0,0 +1,60 @@ +Overview +======== +MKTME (Multi-Key Total Memory Encryption) is a technology that allows +memory encryption on Intel platforms. The main use case for the feature +is virtual machine isolation. The API should apply to a wide range of +use cases. + +Find the Intel Architecture Specification for MKTME here: +https://software.intel.com/sites/default/files/managed/a5/16/Multi-Key-Total-Memory-Encryption-Spec.pdf + +The Encryption Process +---------------------- +Userspace will see MKTME encryption as a Step Process. + +Step 1: Use the MKTME Key Service API to allocate an encryption key. + +Step 2: Use the encrypt_mprotect() system call to protect memory + with the encryption key obtained in Step 1. + +Definitions +----------- +Keys: References to Keys in this document are to Userspace Keys. + These keys are requested by users and jointly managed by the + MKTME Key Service Type, and more broadly by the Kernel Key + Service of which MKTME is a part. + + This document does not intend to document KKS, but only the + MKTME type of the KKS. The options of the KKS can be grouped + into 2 classes for purposes of understanding how MKTME operates + within the broader KKS. + +KeyIDs: References to KeyIDs in this document are to the hardware KeyID + slots that are available on Intel Platforms. A KeyID is a + numerical index into a software programmable slot in the Intel + hardware. Refer to the Intel specification linked above for + details on the implementation of MKTME in Intel platforms. + +Key<-->KeyID Mapping: + The MKTME Key Service maintains a mapping between Keys and KeyIDS. + This mapping is known only to the kernel. Userspace does not need + to know which hardware KeyID slot it's Userspace Key has been + assigned. + +Configuration +------------- + +CONFIG_X86_INTEL_MKTME + MKTME is enabled by selecting CONFIG_X86_INTEL_MKTME on Intel + platforms supporting the MKTME feature. + +mktme_savekeys + mktme_savekeys is a kernel cmdline parameter. + + This parameter allows the kernel to save the user specified + MKTME key payload. Saving this payload means that the MKTME + Key Service can always allow the addition of new physical + packages. If the mktme_savekeys parameter is not present, + users key data will not be saved, and new physical packages + may only be added to the system if no user type MKTME keys + are in use.