Linux-Fsdevel Archive on
help / color / mirror / Atom feed
To: Thomas Gleixner <>,
	Ingo Molnar <>, Borislav Petkov <>,
	Andy Lutomirski <>,
	Peter Zijlstra <>
Cc: Ira Weiny <>,, Dave Hansen <>,
	Dan Williams <>,
	Vishal Verma <>,
	Andrew Morton <>,
	Fenghua Yu <>,,,,,,
Subject: [RFC PATCH 07/15] Documentation/pkeys: Update documentation for kernel pkeys
Date: Tue, 14 Jul 2020 00:02:12 -0700	[thread overview]
Message-ID: <> (raw)
In-Reply-To: <>

From: Ira Weiny <>

Future Intel CPUS will support Protection Key Supervisor (PKS).

Update the protection key documentation to cover pkeys on supervisor

Signed-off-by: Ira Weiny <>
 Documentation/core-api/protection-keys.rst | 81 +++++++++++++++++-----
 1 file changed, 63 insertions(+), 18 deletions(-)

diff --git a/Documentation/core-api/protection-keys.rst b/Documentation/core-api/protection-keys.rst
index ec575e72d0b2..5ac400a5a306 100644
--- a/Documentation/core-api/protection-keys.rst
+++ b/Documentation/core-api/protection-keys.rst
@@ -4,25 +4,33 @@
 Memory Protection Keys
-Memory Protection Keys for Userspace (PKU aka PKEYs) is a feature
-which is found on Intel's Skylake (and later) "Scalable Processor"
-Server CPUs. It will be available in future non-server Intel parts
-and future AMD processors.
-For anyone wishing to test or use this feature, it is available in
-Amazon's EC2 C5 instances and is known to work there using an Ubuntu
-17.04 image.
 Memory Protection Keys provides a mechanism for enforcing page-based
 protections, but without requiring modification of the page tables
-when an application changes protection domains.  It works by
-dedicating 4 previously ignored bits in each page table entry to a
-"protection key", giving 16 possible keys.
+when an application changes protection domains.
+PKeys Userspace (PKU) is a feature which is found on Intel's Skylake "Scalable
+Processor" Server CPUs and later.  And It will be available in future
+non-server Intel parts and future AMD processors.
+Future Intel processors will support Protection Keys for Supervisor pages
+For anyone wishing to test or use user space pkeys, it is available in Amazon's
+EC2 C5 instances and is known to work there using an Ubuntu 17.04 image.
+pkes work by dedicating 4 previously Reserved bits in each page table entry to
+a "protection key", giving 16 possible keys.  User and Supervisor pages are
+treated separately.
-There is also a new user-accessible register (PKRU) with two separate
-bits (Access Disable and Write Disable) for each key.  Being a CPU
-register, PKRU is inherently thread-local, potentially giving each
-thread a different set of protections from every other thread.
+Protections for each page are controlled with per CPU registers for each type
+of page User and Supervisor.  Each of these 32 bit register stores two separate
+bits (Access Disable and Write Disable) for each key.
+For Userspace the register is user-accessible (rdpkru/wrpkru).  For
+Supervisor, the register (MSR_IA32_PKRS) is accessible only to the kernel.
+Being a CPU register, pkes are inherently thread-local, potentially giving
+each thread an independent set of protections from every other thread.
 There are two new instructions (RDPKRU/WRPKRU) for reading and writing
 to the new register.  The feature is only available in 64-bit mode,
@@ -30,8 +38,11 @@ even though there is theoretically space in the PAE PTEs.  These
 permissions are enforced on data access only and have no effect on
 instruction fetches.
+For kernel space rdmsr/wrmsr are used to access the kernel MSRs.
+Syscalls for user space keys
 There are 3 system calls which directly interact with pkeys::
@@ -98,3 +109,37 @@ with a read()::
 The kernel will send a SIGSEGV in both cases, but si_code will be set
 to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
 the plain mprotect() permissions are violated.
+Kernel API for PKS support
+PKS is intended to harden against unwanted access to kernel pages.  But it does
+not completely restrict access under all conditions.  For example the MSR
+setting is not saved/restored during irqs.  Thus the use of PKS is a mitigation
+strategy rather than a form of strict security.
+The following calls are used to allocate, use, and deallocate a pkey which
+defines a 'protection domain' within the kernel.  Setting a pkey value in a
+supervisor mapping adds that mapping to the protection domain.  Then calls can be
+used to enable/disable read and/or write access to all of the pages mapped with
+that key:
+        int pks_key_alloc(const char * const pkey_user);
+        #define PAGE_KERNEL_PKEY(pkey)
+        #define _PAGE_KEY(pkey)
+        int pks_update_protection(int pkey, unsigned long protection);
+        void pks_key_free(int pkey);
+In-kernel users must be prepared to set PAGE_KERNEL_PKEY() permission in the
+page table entries for the mappings they want to ptorect.
+WARNING: It is imperative that callers check for errors from pks_key_alloc()
+because pkeys are a limited resource and so callers should be prepared to work
+without PKS support.
+For admins a debugfs interface provides a list of the current keys in use at:
+        /sys/kernel/debug/x86/pks_keys_allocated
+Some example code can be found in lib/pks/pks_test.c

  parent reply	other threads:[~2020-07-14  7:05 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2020-07-14  7:02 [RFC PATCH 00/15] PKS: Add Protection Keys Supervisor (PKS) support ira.weiny
2020-07-14  7:02 ` [RFC PATCH 01/15] x86/pkeys: Create pkeys_internal.h ira.weiny
2020-07-14  7:02 ` [RFC PATCH 02/15] x86/fpu: Refactor arch_set_user_pkey_access() for PKS support ira.weiny
2020-07-14  7:02 ` [RFC PATCH 03/15] x86/pks: Enable Protection Keys Supervisor (PKS) ira.weiny
2020-07-14  7:02 ` [RFC PATCH 04/15] x86/pks: Preserve the PKRS MSR on context switch ira.weiny
2020-07-14  8:27   ` Peter Zijlstra
2020-07-14 18:53     ` Ira Weiny
2020-07-14 18:56       ` Dave Hansen
2020-07-14 19:05       ` Peter Zijlstra
2020-07-14 19:09         ` Ira Weiny
2020-07-14  7:02 ` [RFC PATCH 05/15] x86/pks: Add PKS kernel API ira.weiny
2020-07-14  7:02 ` [RFC PATCH 06/15] x86/pks: Add a debugfs file for allocated PKS keys ira.weiny
2020-07-14  7:02 ` ira.weiny [this message]
2020-07-14  7:02 ` [RFC PATCH 08/15] x86/pks: Add PKS Test code ira.weiny
2020-07-14  7:02 ` [RFC PATCH 09/15] fs/dax: Remove unused size parameter ira.weiny
2020-07-14  7:02 ` [RFC PATCH 10/15] drivers/dax: Expand lock scope to cover the use of addresses ira.weiny
2020-07-14  7:02 ` [RFC PATCH 11/15] memremap: Add zone device access protection ira.weiny
2020-07-14  8:40   ` Peter Zijlstra
2020-07-14 19:10     ` Ira Weiny
2020-07-14 19:40       ` Peter Zijlstra
2020-07-14  7:02 ` [RFC PATCH 12/15] kmap: Add stray write protection for device pages ira.weiny
2020-07-14  8:44   ` Peter Zijlstra
2020-07-14 19:06     ` Ira Weiny
2020-07-14 19:29       ` Peter Zijlstra
2020-07-14 19:42         ` Dave Hansen
2020-07-14 19:49           ` Peter Zijlstra
2020-07-14 20:00           ` Ira Weiny
2020-07-14  7:02 ` [RFC PATCH 13/15] dax: Stray write protection for dax_direct_access() ira.weiny
2020-07-14  7:02 ` [RFC PATCH 14/15] nvdimm/pmem: Stray write protection for pmem->virt_addr ira.weiny
2020-07-14  7:02 ` [RFC PATCH 15/15] [dax|pmem]: Enable stray write protection ira.weiny

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:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \
    --subject='Re: [RFC PATCH 07/15] Documentation/pkeys: Update documentation for kernel pkeys' \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

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).