man7/pkeys.7

   1 .\" Copyright (C) 2016 Intel Corporation
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .TH pkeys 7 (date) "Linux man-pages (unreleased)"
   6 .SH NAME
   7 pkeys \- overview of Memory Protection Keys
   8 .SH DESCRIPTION
   9 Memory Protection Keys (pkeys) are an extension to existing
  10 page-based memory permissions.
  11 Normal page permissions using
  12 page tables require expensive system calls and TLB invalidations
  13 when changing permissions.
  14 Memory Protection Keys provide a mechanism for changing
  15 protections without requiring modification of the page tables on
  16 every permission change.
  17 .P
  18 To use pkeys, software must first "tag" a page in the page tables
  19 with a pkey.
  20 After this tag is in place, an application only has
  21 to change the contents of a register in order to remove write
  22 access, or all access to a tagged page.
  23 .P
  24 Protection keys work in conjunction with the existing
  25 .BR PROT_READ ,
  26 .BR PROT_WRITE ,
  27 and
  28 .B PROT_EXEC
  29 permissions passed to system calls such as
  30 .BR mprotect (2)
  31 and
  32 .BR mmap (2),
  33 but always act to further restrict these traditional permission
  34 mechanisms.
  35 .P
  36 If a process performs an access that violates pkey
  37 restrictions, it receives a
  38 .B SIGSEGV
  39 signal.
  40 See
  41 .BR sigaction (2)
  42 for details of the information available with that signal.
  43 .P
  44 To use the pkeys feature, the processor must support it, and the kernel
  45 must contain support for the feature on a given processor.
  46 As of early 2016 only future Intel x86 processors are supported,
  47 and this hardware supports 16 protection keys in each process.
  48 However, pkey 0 is used as the default key, so a maximum of 15
  49 are available for actual application use.
  50 The default key is assigned to any memory region for which a
  51 pkey has not been explicitly assigned via
  52 .BR pkey_mprotect (2).
  53 .P
  54 Protection keys have the potential to add a layer of security and
  55 reliability to applications.
  56 But they have not been primarily designed as
  57 a security feature.
  58 For instance, WRPKRU is a completely unprivileged
  59 instruction, so pkeys are useless in any case that an attacker controls
  60 the PKRU register or can execute arbitrary instructions.
  61 .P
  62 Applications should be very careful to ensure that they do not "leak"
  63 protection keys.
  64 For instance, before calling
  65 .BR pkey_free (2),
  66 the application should be sure that no memory has that pkey assigned.
  67 If the application left the freed pkey assigned, a future user of
  68 that pkey might inadvertently change the permissions of an unrelated
  69 data structure, which could impact security or stability.
  70 The kernel currently allows in-use pkeys to have
  71 .BR pkey_free (2)
  72 called on them because it would have processor or memory performance
  73 implications to perform the additional checks needed to disallow it.
  74 Implementation of the necessary checks is left up to applications.
  75 Applications may implement these checks by searching the
  76 .IR /proc/ pid /smaps
  77 file for memory regions with the pkey assigned.
  78 Further details can be found in
  79 .BR proc (5).
  80 .P
  81 Any application wanting to use protection keys needs to be able
  82 to function without them.
  83 They might be unavailable because the hardware that the
  84 application runs on does not support them, the kernel code does
  85 not contain support, the kernel support has been disabled, or
  86 because the keys have all been allocated, perhaps by a library
  87 the application is using.
  88 It is recommended that applications wanting to use protection
  89 keys should simply call
  90 .BR pkey_alloc (2)
  91 and test whether the call succeeds,
  92 instead of attempting to detect support for the
  93 feature in any other way.
  94 .P
  95 Although unnecessary, hardware support for protection keys may be
  96 enumerated with the
  97 .I cpuid
  98 instruction.
  99 Details of how to do this can be found in the Intel Software
 100 Developers Manual.
 101 The kernel performs this enumeration and exposes the information in
 102 .I /proc/cpuinfo
 103 under the "flags" field.
 104 The string "pku" in this field indicates hardware support for protection
 105 keys and the string "ospke" indicates that the kernel contains and has
 106 enabled protection keys support.
 107 .P
 108 Applications using threads and protection keys should be especially
 109 careful.
 110 Threads inherit the protection key rights of the parent at the time
 111 of the
 112 .BR clone (2),
 113 system call.
 114 Applications should either ensure that their own permissions are
 115 appropriate for child threads at the time when
 116 .BR clone (2)
 117 is called, or ensure that each child thread can perform its
 118 own initialization of protection key rights.
 119 .\"
 120 .SS Signal Handler Behavior
 121 Each time a signal handler is invoked (including nested signals), the
 122 thread is temporarily given a new, default set of protection key rights
 123 that override the rights from the interrupted context.
 124 This means that applications must re-establish their desired protection
 125 key rights upon entering a signal handler if the desired rights differ
 126 from the defaults.
 127 The rights of any interrupted context are restored when the signal
 128 handler returns.
 129 .P
 130 This signal behavior is unusual and is due to the fact that the x86 PKRU
 131 register (which stores protection key access rights) is managed with the
 132 same hardware mechanism (XSAVE) that manages floating-point registers.
 133 The signal behavior is the same as that of floating-point registers.
 134 .\"
 135 .SS Protection Keys system calls
 136 The Linux kernel implements the following pkey-related system calls:
 137 .BR pkey_mprotect (2),
 138 .BR pkey_alloc (2),
 139 and
 140 .BR pkey_free (2).
 141 .P
 142 The Linux pkey system calls are available only if the kernel was
 143 configured and built with the
 144 .B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS
 145 option.
 146 .SH EXAMPLES
 147 The program below allocates a page of memory with read and write permissions.
 148 It then writes some data to the memory and successfully reads it
 149 back.
 150 After that, it attempts to allocate a protection key and
 151 disallows access to the page by using the WRPKRU instruction.
 152 It then tries to access the page,
 153 which we now expect to cause a fatal signal to the application.
 154 .P
 155 .in +4n
 156 .EX
 157 .RB "$" " ./a.out"
 158 buffer contains: 73
 159 about to read buffer again...
 160 Segmentation fault (core dumped)
 161 .EE
 162 .in
 163 .SS Program source
 164 \&
 165 .EX
 166 #define _GNU_SOURCE
 167 #include <err.h>
 168 #include <unistd.h>
 169 #include <stdio.h>
 170 #include <stdlib.h>
 171 #include <sys/mman.h>
 172 \&
 173 int
 174 main(void)
 175 {
 176     int status;
 177     int pkey;
 178     int *buffer;
 179 \&
 180     /*
 181      * Allocate one page of memory.
 182      */
 183     buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE,
 184                   MAP_ANONYMOUS | MAP_PRIVATE, \-1, 0);
 185     if (buffer == MAP_FAILED)
 186         err(EXIT_FAILURE, "mmap");
 187 \&
 188     /*
 189      * Put some random data into the page (still OK to touch).
 190      */
 191     *buffer = __LINE__;
 192     printf("buffer contains: %d\en", *buffer);
 193 \&
 194     /*
 195      * Allocate a protection key:
 196      */
 197     pkey = pkey_alloc(0, 0);
 198     if (pkey == \-1)
 199         err(EXIT_FAILURE, "pkey_alloc");
 200 \&
 201     /*
 202      * Disable access to any memory with "pkey" set,
 203      * even though there is none right now.
 204      */
 205     status = pkey_set(pkey, PKEY_DISABLE_ACCESS);
 206     if (status)
 207         err(EXIT_FAILURE, "pkey_set");
 208 \&
 209     /*
 210      * Set the protection key on "buffer".
 211      * Note that it is still read/write as far as mprotect() is
 212      * concerned and the previous pkey_set() overrides it.
 213      */
 214     status = pkey_mprotect(buffer, getpagesize(),
 215                            PROT_READ | PROT_WRITE, pkey);
 216     if (status == \-1)
 217         err(EXIT_FAILURE, "pkey_mprotect");
 218 \&
 219     printf("about to read buffer again...\en");
 220 \&
 221     /*
 222      * This will crash, because we have disallowed access.
 223      */
 224     printf("buffer contains: %d\en", *buffer);
 225 \&
 226     status = pkey_free(pkey);
 227     if (status == \-1)
 228         err(EXIT_FAILURE, "pkey_free");
 229 \&
 230     exit(EXIT_SUCCESS);
 231 }
 232 .EE
 233 .SH SEE ALSO
 234 .BR pkey_alloc (2),
 235 .BR pkey_free (2),
 236 .BR pkey_mprotect (2),
 237 .BR sigaction (2)