From: "Kirill A. Shutemov" <kirill@shutemov.name>
To: Andrew Morton <akpm@linux-foundation.org>,
x86@kernel.org, Thomas Gleixner <tglx@linutronix.de>,
Ingo Molnar <mingo@redhat.com>, "H. Peter Anvin" <hpa@zytor.com>,
Borislav Petkov <bp@alien8.de>,
Peter Zijlstra <peterz@infradead.org>,
Andy Lutomirski <luto@amacapital.net>,
David Howells <dhowells@redhat.com>
Cc: Kees Cook <keescook@chromium.org>,
Dave Hansen <dave.hansen@intel.com>,
Kai Huang <kai.huang@linux.intel.com>,
Jacob Pan <jacob.jun.pan@linux.intel.com>,
Alison Schofield <alison.schofield@intel.com>,
linux-mm@kvack.org, kvm@vger.kernel.org,
keyrings@vger.kernel.org, linux-kernel@vger.kernel.org,
"Kirill A . Shutemov" <kirill.shutemov@linux.intel.com>
Subject: [PATCHv2 58/59] x86/mktme: Document the MKTME API for anonymous memory encryption
Date: Wed, 31 Jul 2019 18:08:12 +0300 [thread overview]
Message-ID: <20190731150813.26289-59-kirill.shutemov@linux.intel.com> (raw)
In-Reply-To: <20190731150813.26289-1-kirill.shutemov@linux.intel.com>
From: Alison Schofield <alison.schofield@intel.com>
Signed-off-by: Alison Schofield <alison.schofield@intel.com>
Signed-off-by: Kirill A. Shutemov <kirill.shutemov@linux.intel.com>
---
Documentation/x86/mktme/index.rst | 1 +
Documentation/x86/mktme/mktme_encrypt.rst | 56 +++++++++++++++++++++++
2 files changed, 57 insertions(+)
create mode 100644 Documentation/x86/mktme/mktme_encrypt.rst
diff --git a/Documentation/x86/mktme/index.rst b/Documentation/x86/mktme/index.rst
index 8cf2b7d62091..ca3c76adc596 100644
--- a/Documentation/x86/mktme/index.rst
+++ b/Documentation/x86/mktme/index.rst
@@ -9,3 +9,4 @@ Multi-Key Total Memory Encryption (MKTME)
mktme_mitigations
mktme_configuration
mktme_keys
+ mktme_encrypt
diff --git a/Documentation/x86/mktme/mktme_encrypt.rst b/Documentation/x86/mktme/mktme_encrypt.rst
new file mode 100644
index 000000000000..6dc8ae11f1cb
--- /dev/null
+++ b/Documentation/x86/mktme/mktme_encrypt.rst
@@ -0,0 +1,56 @@
+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 memory that is to be protected must be mapped *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);
--
2.21.0
next prev parent reply other threads:[~2019-07-31 15:14 UTC|newest]
Thread overview: 68+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-07-31 15:07 [PATCHv2 00/59] Intel MKTME enabling Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 01/59] mm: Do no merge VMAs with different encryption KeyIDs Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 02/59] mm: Add helpers to setup zero page mappings Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 03/59] mm/ksm: Do not merge pages with different KeyIDs Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 04/59] mm/page_alloc: Unify alloc_hugepage_vma() Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 05/59] mm/page_alloc: Handle allocation for encrypted memory Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 06/59] mm/khugepaged: Handle encrypted pages Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 07/59] x86/mm: Mask out KeyID bits from page table entry pfn Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 08/59] x86/mm: Introduce helpers to read number, shift and mask of KeyIDs Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 09/59] x86/mm: Store bitmask of the encryption algorithms supported by MKTME Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 10/59] x86/mm: Preserve KeyID on pte_modify() and pgprot_modify() Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 11/59] x86/mm: Detect MKTME early Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 12/59] x86/mm: Add a helper to retrieve KeyID for a page Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 13/59] x86/mm: Add a helper to retrieve KeyID for a VMA Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 14/59] x86/mm: Add hooks to allocate and free encrypted pages Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 15/59] x86/mm: Map zero pages into encrypted mappings correctly Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 16/59] x86/mm: Rename CONFIG_RANDOMIZE_MEMORY_PHYSICAL_PADDING Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 17/59] x86/mm: Allow to disable MKTME after enumeration Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 18/59] x86/mm: Calculate direct mapping size Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 19/59] x86/mm: Implement syncing per-KeyID direct mappings Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 20/59] x86/mm: Handle encrypted memory in page_to_virt() and __pa() Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 21/59] mm/page_ext: Export lookup_page_ext() symbol Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 22/59] mm/rmap: Clear vma->anon_vma on unlink_anon_vmas() Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 23/59] x86/pconfig: Set an activated algorithm in all MKTME commands Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 24/59] keys/mktme: Introduce a Kernel Key Service for MKTME Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 25/59] keys/mktme: Preparse the MKTME key payload Kirill A. Shutemov
2019-08-05 11:58 ` Ben Boeckel
2019-08-05 20:31 ` Alison Schofield
2019-08-13 13:06 ` Ben Boeckel
2019-07-31 15:07 ` [PATCHv2 26/59] keys/mktme: Instantiate MKTME keys Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 27/59] keys/mktme: Destroy " Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 28/59] keys/mktme: Move the MKTME payload into a cache aligned structure Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 29/59] keys/mktme: Set up PCONFIG programming targets for MKTME keys Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 30/59] keys/mktme: Program MKTME keys into the platform hardware Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 31/59] keys/mktme: Set up a percpu_ref_count for MKTME keys Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 32/59] keys/mktme: Clear the key programming from the MKTME hardware Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 33/59] keys/mktme: Require CAP_SYS_RESOURCE capability for MKTME keys Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 34/59] acpi: Remove __init from acpi table parsing functions Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 35/59] acpi/hmat: Determine existence of an ACPI HMAT Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 36/59] keys/mktme: Require ACPI HMAT to register the MKTME Key Service Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 37/59] acpi/hmat: Evaluate topology presented in ACPI HMAT for MKTME Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 38/59] keys/mktme: Do not allow key creation in unsafe topologies Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 39/59] keys/mktme: Support CPU hotplug for MKTME key service Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 40/59] keys/mktme: Block memory hotplug additions when MKTME is enabled Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 41/59] mm: Generalize the mprotect implementation to support extensions Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 42/59] syscall/x86: Wire up a system call for MKTME encryption keys Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 43/59] x86/mm: Set KeyIDs in encrypted VMAs for MKTME Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 44/59] mm: Add the encrypt_mprotect() system call " Kirill A. Shutemov
2019-07-31 15:07 ` [PATCHv2 45/59] x86/mm: Keep reference counts on hardware key usage " Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 46/59] mm: Restrict MKTME memory encryption to anonymous VMAs Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 47/59] kvm, x86, mmu: setup MKTME keyID to spte for given PFN Kirill A. Shutemov
2019-08-06 20:26 ` Lendacky, Thomas
2019-08-07 14:28 ` Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 48/59] iommu/vt-d: Support MKTME in DMA remapping Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 49/59] x86/mm: introduce common code for mem encryption Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 50/59] x86/mm: Use common code for DMA memory encryption Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 51/59] x86/mm: Disable MKTME on incompatible platform configurations Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 52/59] x86/mm: Disable MKTME if not all system memory supports encryption Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 53/59] x86: Introduce CONFIG_X86_INTEL_MKTME Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 54/59] x86/mktme: Overview of Multi-Key Total Memory Encryption Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 55/59] x86/mktme: Document the MKTME provided security mitigations Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 56/59] x86/mktme: Document the MKTME kernel configuration requirements Kirill A. Shutemov
2019-07-31 15:08 ` [PATCHv2 57/59] x86/mktme: Document the MKTME Key Service API Kirill A. Shutemov
2019-08-05 11:58 ` Ben Boeckel
2019-08-05 20:44 ` Alison Schofield
2019-08-13 13:07 ` Ben Boeckel
2019-07-31 15:08 ` Kirill A. Shutemov [this message]
2019-07-31 15:08 ` [PATCHv2 59/59] x86/mktme: Demonstration program using the MKTME APIs Kirill A. Shutemov
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=20190731150813.26289-59-kirill.shutemov@linux.intel.com \
--to=kirill@shutemov.name \
--cc=akpm@linux-foundation.org \
--cc=alison.schofield@intel.com \
--cc=bp@alien8.de \
--cc=dave.hansen@intel.com \
--cc=dhowells@redhat.com \
--cc=hpa@zytor.com \
--cc=jacob.jun.pan@linux.intel.com \
--cc=kai.huang@linux.intel.com \
--cc=keescook@chromium.org \
--cc=keyrings@vger.kernel.org \
--cc=kirill.shutemov@linux.intel.com \
--cc=kvm@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=linux-mm@kvack.org \
--cc=luto@amacapital.net \
--cc=mingo@redhat.com \
--cc=peterz@infradead.org \
--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 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).