From patchwork Fri Sep 7 22:34:07 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Alison Schofield X-Patchwork-Id: 10592643 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 2961714E2 for ; Fri, 7 Sep 2018 22:33:33 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 16A682B030 for ; Fri, 7 Sep 2018 22:33:33 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id 09D3C2B12D; Fri, 7 Sep 2018 22:33:33 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-2.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_NONE autolearn=ham version=3.3.1 Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 4F5792B030 for ; Fri, 7 Sep 2018 22:33:32 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id C105E8E0003; Fri, 7 Sep 2018 18:33:30 -0400 (EDT) Delivered-To: linux-mm-outgoing@kvack.org Received: by kanga.kvack.org (Postfix, from userid 40) id B9A418E0001; Fri, 7 Sep 2018 18:33:30 -0400 (EDT) X-Original-To: int-list-linux-mm@kvack.org X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id A3B6C8E0003; Fri, 7 Sep 2018 18:33:30 -0400 (EDT) X-Original-To: linux-mm@kvack.org X-Delivered-To: linux-mm@kvack.org Received: from mail-pl1-f198.google.com (mail-pl1-f198.google.com [209.85.214.198]) by kanga.kvack.org (Postfix) with ESMTP id 5CB048E0001 for ; Fri, 7 Sep 2018 18:33:30 -0400 (EDT) Received: by mail-pl1-f198.google.com with SMTP id bg5-v6so7631921plb.20 for ; Fri, 07 Sep 2018 15:33:30 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-original-authentication-results:x-gm-message-state:date:from:to :cc:subject:message-id:references:mime-version:content-disposition :in-reply-to:user-agent; bh=7xGrl4dVGT5M51JL53umoUFE/B4+nhH2JaSlZUL3tiw=; b=C1kQpNsMcvLTcZuVw2utYoh1dK74WN7hllK6FevQV4PB/X0cuInbI2P6oCN7+roY7y M/i/WlHslp+2IEBEvwJyMKdNv4KzAeta7vFDOf+KI81/w1ngJ1aw4TaWYqCK/NrVgzrw C9s+rMdMBEiKXFS5ZBMhFjWSlPTgYjFr2kP0EYHXQSY3d5Pypyys18KD4qi9p2p4Fuo4 DyaSauALmqIYTmz15ySCvvuTy1okK+2ZlfZvgSEPeBsnXv/9I8ZrEa4my2dXMW5Xf0Sb bqR1vg0HalpciRr0uo3oEdtWXsw/+6VxlBwfzuVXBgXWPXHKZpoEGe0tuRK0OO6ad4cM uIcQ== X-Original-Authentication-Results: mx.google.com; spf=pass (google.com: domain of alison.schofield@intel.com designates 134.134.136.65 as permitted sender) smtp.mailfrom=alison.schofield@intel.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com X-Gm-Message-State: APzg51B7x8ynR02vdNzKO8E9ZdX6qNFQvwBudaoxNa2RGCgqeTrsZPXx MT4KqpEpnllmEYiO8vkOJMYOxZ0qjeXYdtFWuL8rdNwU3y17DX9M3xx8g9QSmpbZ755s3dF2HLa //LCYs5U5yNMqZ26eFzaWb7GFDrzXxV69xFcTjDf82l2e1y+fJPGj6Z9hgnmnPMQytQ== X-Received: by 2002:a63:447:: with SMTP id 68-v6mr10512216pge.409.1536359609992; Fri, 07 Sep 2018 15:33:29 -0700 (PDT) X-Google-Smtp-Source: ANB0Vdad9gXSGlCA0+xixIvUZIw2IbObO3cmGD2u6qLzOiPCzYC3+YojdcqfPYoD2JQu2ASoPEtt X-Received: by 2002:a63:447:: with SMTP id 68-v6mr10512152pge.409.1536359608754; Fri, 07 Sep 2018 15:33:28 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1536359608; cv=none; d=google.com; s=arc-20160816; b=tW+eF7quK0GMxRDBywV6TJFqppoM/p49pyg6Q0NlVgy5L80EgmMFNEdjr1bC3XM2Ik sPGAwfYW9UzBElh6QTMvmp8WKjp9VwSWGUO9cRSz3tLJGMgXTDw/c1tyw1y+QZjb+mCR IqoIMNoKmsMYKbqowZkVCccoCo5RDfi/v2MvXrvAkcMUh6e8CIc0P5swhiQfi1rk0+LO EmF6dWufsk6evdiZg2yp7Cu9qKoqJaZ4eoRHm1t7Frq0AsBsUIQ1ck2CoM4EwBLfAUVI hwmG2t2ueRZUlHAbapcHCQqB3eLBOaCws/blI3qXrUE4YeA79LDmt6M6coXAD7zUvHxe P5zg== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=user-agent:in-reply-to:content-disposition:mime-version:references :message-id:subject:cc:to:from:date; bh=7xGrl4dVGT5M51JL53umoUFE/B4+nhH2JaSlZUL3tiw=; b=I76zC/LxfafsIyjdoDblDn0NE3nkMRgW/4g6oQ5ohBz0Exan7x5rdHOcKWOD26PQAF 6FtKKlrKR6gcsy39g881aMM3b/mtuw0jT9TBwVTaktpLWQKf8a/0kUKIECbjZaM7FFRy xMVulB3ldc4xAtt68CeGmYh6IYSLAE3lhRE2xNK27NW6pMBqZONvwurAJo0gB+921O8c RMvWR/whgiZBIfMMNGuXmhgueSe+/4dIoMJob24dmzbgs+vDY+kAhrhYMQorJeCArIMz wL2wXzWhwu5DeOiBTUcT8liu+meKUsQkbMhDv9eu1nHhj8ASE8bK6jQ7vg3moVNlytHH voRQ== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: domain of alison.schofield@intel.com designates 134.134.136.65 as permitted sender) smtp.mailfrom=alison.schofield@intel.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com Received: from mga03.intel.com (mga03.intel.com. [134.134.136.65]) by mx.google.com with ESMTPS id v61-v6si8769505plb.448.2018.09.07.15.33.28 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 07 Sep 2018 15:33:28 -0700 (PDT) Received-SPF: pass (google.com: domain of alison.schofield@intel.com designates 134.134.136.65 as permitted sender) client-ip=134.134.136.65; Authentication-Results: mx.google.com; spf=pass (google.com: domain of alison.schofield@intel.com designates 134.134.136.65 as permitted sender) smtp.mailfrom=alison.schofield@intel.com; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=intel.com X-Amp-Result: UNSCANNABLE X-Amp-File-Uploaded: False Received: from orsmga002.jf.intel.com ([10.7.209.21]) by orsmga103.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 07 Sep 2018 15:33:28 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.53,344,1531810800"; d="scan'208";a="89921061" Received: from alison-desk.jf.intel.com ([10.54.74.53]) by orsmga002.jf.intel.com with ESMTP; 07 Sep 2018 15:33:24 -0700 Date: Fri, 7 Sep 2018 15:34:07 -0700 From: Alison Schofield To: dhowells@redhat.com, tglx@linutronix.de Cc: Kai Huang , Jun Nakajima , Kirill Shutemov , Dave Hansen , Jarkko Sakkinen , 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 Message-ID: References: MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: User-Agent: Mutt/1.5.24 (2015-08-30) X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: X-Virus-Scanned: ClamAV using ClamSMTP Document the API's used for MKTME on Intel platforms. MKTME: Multi-KEY Total Memory Encryption Signed-off-by: Alison Schofield --- 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 + + 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); +