[RFC 01/12] docs/x86: Document the Multi-Key Total Memory Encryption API
Huang, Kai
kai.huang at intel.com
Tue Sep 11 00:33:33 UTC 2018
> -----Original Message-----
> From: owner-linux-mm at kvack.org [mailto:owner-linux-mm at kvack.org] On
> Behalf Of Alison Schofield
> Sent: Tuesday, September 11, 2018 12:13 PM
> To: Huang, Kai <kai.huang at intel.com>
> Cc: dhowells at redhat.com; tglx at linutronix.de; Nakajima, Jun
> <jun.nakajima at intel.com>; Shutemov, Kirill <kirill.shutemov at intel.com>;
> Hansen, Dave <dave.hansen at intel.com>; Sakkinen, Jarkko
> <jarkko.sakkinen at intel.com>; jmorris at namei.org; keyrings at vger.kernel.org;
> linux-security-module at vger.kernel.org; mingo at redhat.com; hpa at zytor.com;
> x86 at kernel.org; linux-mm at kvack.org
> Subject: Re: [RFC 01/12] docs/x86: Document the Multi-Key Total Memory
> Encryption API
>
> On Sun, Sep 09, 2018 at 06:28:28PM -0700, Huang, Kai wrote:
> >
> > > -----Original Message-----
> > > From: owner-linux-mm at kvack.org [mailto:owner-linux-mm at kvack.org] On
> > > Behalf Of Alison Schofield
> > > Sent: Saturday, September 8, 2018 10:34 AM
> > > To: dhowells at redhat.com; tglx at linutronix.de
> > > Cc: Huang, Kai <kai.huang at intel.com>; Nakajima, Jun
> > > <jun.nakajima at intel.com>; Shutemov, Kirill
> > > <kirill.shutemov at intel.com>; Hansen, Dave <dave.hansen at intel.com>;
> > > Sakkinen, Jarkko <jarkko.sakkinen at intel.com>; jmorris at namei.org;
> > > keyrings at vger.kernel.org; linux-security-module at vger.kernel.org;
> > > mingo at redhat.com; hpa at zytor.com; x86 at kernel.org; linux-
> mm at kvack.org
> > > Subject: [RFC 01/12] docs/x86: Document the Multi-Key Total Memory
> > > Encryption API
> > >
> > > Document the API's used for MKTME on Intel platforms.
> > > MKTME: Multi-KEY Total Memory Encryption
> > >
> > > Signed-off-by: Alison Schofield <alison.schofield at 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.
> >
> > Why 3 to 63 keys? Architecturally we are able to support up to 15-bit keyID,
> although in the first generation server we only support 6-bit keyID, which is 63
> key/keyIDs (excluding keyID 0, which is TME's keyID).
>
> My understanding is that low level SKU's could have as few as 3 bits available to
> hold the keyid, and that the max is 6 bits, hence 64.
> I probably don't need to be stating that level of detail here, but rather just
> iterate the important point that the resource is limited!
>
> >
> > > + 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.
> >
> > I think it's better to separate encrypt_mprotect() into another doc so both
> parts can be reviewed easier.
>
> I can do that.
> Also, I do know I need man page for that too.
> >
> > > +
> > > +====================== 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.
> ^^^^^^^ should be tweak
>
> >
> > This is not true. The spec says in CPU generated random mode, both 'key' and
> 'tweak' part are used to generate the final key and tweak respectively.
> >
> > Actually, simple 'XOR' is used to generate the final key:
> >
> > case KEYID_SET_KEY_RANDOM:
> > ......
> > (* Mix user supplied entropy to the data key and tweak key *)
> > TMP_RND_DATA_KEY = TMP_RND_KEY XOR
> > TMP_KEY_PROGRAM_STRUCT.KEY_FIELD_1.BYTES[15:0];
> > TMP_RND_TWEAK_KEY = TMP_RND_TWEAK_KEY XOR
> > TMP_KEY_PROGRAM_STRUCT.KEY_FIELD_2.BYTES[15:0];
> >
> > So I think we can either just remove 'entropy' parameter, since we can use
> both 'userkey' and 'tweak' even for random key mode.
> >
> > In fact, which might be better IMHO, we can simply disallow or ignore
> 'userkey' and 'tweak' part for random key mode, since if we allow user to specify
> both entropies, and if user passes value with all 1, we are effectively making the
> key and tweak to be all 1, which is not random anymore.
> >
> > Instead, kernel can generate random for both entropies, or we can simply uses
> 0, ignoring user input.
>
> Kai,
> I think my typo above, threw you off. We have the same understanding of the
> key fields.
>
> Is this the structure you are suggesting?
>
> Options
>
> key_type= "user" or "CPU"
>
> key= If key_type == user
> key= is the data key
> If key_type == CPU
> key= is not required
> if key= is present
> it is entropy to be mixed with
> CPU generated data key
>
> tweak= If key_type == user
> tweak= is the tweak key
> If key_type == CPU
> tweak= is not required
> if tweak= is present
> it is entropy to be mixed with
> CPU generated tweak key
Exactly.
Although I am not sure whether we should support other 2 modes: Clear key and no encryption;
Thanks,
-Kai
>
>
> Alison
> >
> > Thanks,
> > -Kai
>
> ........snip...........
More information about the Linux-security-module-archive
mailing list