Documentation/core-api/protection-keys.rst

   1 .. SPDX-License-Identifier: GPL-2.0
   2
   3 ======================
   4 Memory Protection Keys
   5 ======================
   6
   7 Memory Protection Keys provide a mechanism for enforcing page-based
   8 protections, but without requiring modification of the page tables when an
   9 application changes protection domains.
  10
  11 Pkeys Userspace (PKU) is a feature which can be found on:
  12         * Intel server CPUs, Skylake and later
  13         * Intel client CPUs, Tiger Lake (11th Gen Core) and later
  14         * Future AMD CPUs
  15         * arm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE)
  16
  17 x86_64
  18 ======
  19 Pkeys work by dedicating 4 previously Reserved bits in each page table entry to
  20 a "protection key", giving 16 possible keys.
  21
  22 Protections for each key are defined with a per-CPU user-accessible register
  23 (PKRU).  Each of these is a 32-bit register storing two bits (Access Disable
  24 and Write Disable) for each of 16 keys.
  25
  26 Being a CPU register, PKRU is inherently thread-local, potentially giving each
  27 thread a different set of protections from every other thread.
  28
  29 There are two instructions (RDPKRU/WRPKRU) for reading and writing to the
  30 register.  The feature is only available in 64-bit mode, even though there is
  31 theoretically space in the PAE PTEs.  These permissions are enforced on data
  32 access only and have no effect on instruction fetches.
  33
  34 arm64
  35 =====
  36
  37 Pkeys use 3 bits in each page table entry, to encode a "protection key index",
  38 giving 8 possible keys.
  39
  40 Protections for each key are defined with a per-CPU user-writable system
  41 register (POR_EL0).  This is a 64-bit register encoding read, write and execute
  42 overlay permissions for each protection key index.
  43
  44 Being a CPU register, POR_EL0 is inherently thread-local, potentially giving
  45 each thread a different set of protections from every other thread.
  46
  47 Unlike x86_64, the protection key permissions also apply to instruction
  48 fetches.
  49
  50 Syscalls
  51 ========
  52
  53 There are 3 system calls which directly interact with pkeys::
  54
  55         int pkey_alloc(unsigned long flags, unsigned long init_access_rights)
  56         int pkey_free(int pkey);
  57         int pkey_mprotect(unsigned long start, size_t len,
  58                           unsigned long prot, int pkey);
  59
  60 Before a pkey can be used, it must first be allocated with pkey_alloc().  An
  61 application writes to the architecture specific CPU register directly in order
  62 to change access permissions to memory covered with a key.  In this example
  63 this is wrapped by a C function called pkey_set().
  64 ::
  65
  66         int real_prot = PROT_READ|PROT_WRITE;
  67         pkey = pkey_alloc(0, PKEY_DISABLE_WRITE);
  68         ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0);
  69         ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey);
  70         ... application runs here
  71
  72 Now, if the application needs to update the data at 'ptr', it can
  73 gain access, do the update, then remove its write access::
  74
  75         pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE
  76         *ptr = foo; // assign something
  77         pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again
  78
  79 Now when it frees the memory, it will also free the pkey since it
  80 is no longer in use::
  81
  82         munmap(ptr, PAGE_SIZE);
  83         pkey_free(pkey);
  84
  85 .. note:: pkey_set() is a wrapper around writing to the CPU register.
  86           Example implementations can be found in
  87           tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h
  88
  89 Behavior
  90 ========
  91
  92 The kernel attempts to make protection keys consistent with the
  93 behavior of a plain mprotect().  For instance if you do this::
  94
  95         mprotect(ptr, size, PROT_NONE);
  96         something(ptr);
  97
  98 you can expect the same effects with protection keys when doing this::
  99
 100         pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ);
 101         pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey);
 102         something(ptr);
 103
 104 That should be true whether something() is a direct access to 'ptr'
 105 like::
 106
 107         *ptr = foo;
 108
 109 or when the kernel does the access on the application's behalf like
 110 with a read()::
 111
 112         read(fd, ptr, 1);
 113
 114 The kernel will send a SIGSEGV in both cases, but si_code will be set
 115 to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when
 116 the plain mprotect() permissions are violated.
 117
 118 Note that kernel accesses from a kthread (such as io_uring) will use a default
 119 value for the protection key register and so will not be consistent with
 120 userspace's value of the register or mprotect().