1pkeys(7)               Miscellaneous Information Manual               pkeys(7)
2
3
4

NAME

6       pkeys - overview of Memory Protection Keys
7

DESCRIPTION

9       Memory  Protection Keys (pkeys) are an extension to existing page-based
10       memory permissions.  Normal page permissions using page tables  require
11       expensive system calls and TLB invalidations when changing permissions.
12       Memory Protection Keys provide a  mechanism  for  changing  protections
13       without  requiring  modification of the page tables on every permission
14       change.
15
16       To use pkeys, software must first "tag" a page in the page tables  with
17       a  pkey.  After this tag is in place, an application only has to change
18       the contents of a register in order to remove write access, or all  ac‐
19       cess to a tagged page.
20
21       Protection  keys  work  in  conjunction  with  the  existing PROT_READ,
22       PROT_WRITE, and PROT_EXEC permissions passed to system  calls  such  as
23       mprotect(2)  and mmap(2), but always act to further restrict these tra‐
24       ditional permission mechanisms.
25
26       If a process performs an access that violates pkey restrictions, it re‐
27       ceives  a SIGSEGV signal.  See sigaction(2) for details of the informa‐
28       tion available with that signal.
29
30       To use the pkeys feature, the processor must support it, and the kernel
31       must contain support for the feature on a given processor.  As of early
32       2016 only future Intel x86 processors are supported, and this  hardware
33       supports  16  protection keys in each process.  However, pkey 0 is used
34       as the default key, so a maximum of 15 are available for actual  appli‐
35       cation use.  The default key is assigned to any memory region for which
36       a pkey has not been explicitly assigned via pkey_mprotect(2).
37
38       Protection keys have the potential to add a layer of security and reli‐
39       ability  to applications.  But they have not been primarily designed as
40       a security feature.  For instance, WRPKRU is a completely  unprivileged
41       instruction, so pkeys are useless in any case that an attacker controls
42       the PKRU register or can execute arbitrary instructions.
43
44       Applications should be very careful to ensure that they do  not  "leak"
45       protection keys.  For instance, before calling pkey_free(2), the appli‐
46       cation should be sure that no memory has that pkey  assigned.   If  the
47       application  left  the  freed pkey assigned, a future user of that pkey
48       might inadvertently change the permissions of an unrelated data  struc‐
49       ture,  which  could impact security or stability.  The kernel currently
50       allows in-use pkeys to have pkey_free(2)  called  on  them  because  it
51       would  have processor or memory performance implications to perform the
52       additional checks needed to disallow it.  Implementation of the  neces‐
53       sary  checks  is  left  up to applications.  Applications may implement
54       these checks by searching the /proc/pid/smaps file for  memory  regions
55       with the pkey assigned.  Further details can be found in proc(5).
56
57       Any  application  wanting  to  use  protection keys needs to be able to
58       function without them.  They might be unavailable because the  hardware
59       that  the  application  runs  on does not support them, the kernel code
60       does not contain support, the kernel support has been disabled, or  be‐
61       cause the keys have all been allocated, perhaps by a library the appli‐
62       cation is using.  It is recommended that applications  wanting  to  use
63       protection  keys  should simply call pkey_alloc(2) and test whether the
64       call succeeds, instead of attempting to detect support for the  feature
65       in any other way.
66
67       Although  unnecessary, hardware support for protection keys may be enu‐
68       merated with the cpuid instruction.  Details of how to do this  can  be
69       found  in  the  Intel  Software Developers Manual.  The kernel performs
70       this enumeration and exposes the information in /proc/cpuinfo under the
71       "flags"  field.  The string "pku" in this field indicates hardware sup‐
72       port for protection keys and the string "ospke" indicates that the ker‐
73       nel contains and has enabled protection keys support.
74
75       Applications  using  threads  and  protection keys should be especially
76       careful.  Threads inherit the protection key rights of  the  parent  at
77       the  time of the clone(2), system call.  Applications should either en‐
78       sure that their own permissions are appropriate for  child  threads  at
79       the  time when clone(2) is called, or ensure that each child thread can
80       perform its own initialization of protection key rights.
81
82   Signal Handler Behavior
83       Each time a signal handler is invoked (including nested  signals),  the
84       thread is temporarily given a new, default set of protection key rights
85       that override the rights from the interrupted context.  This means that
86       applications must re-establish their desired protection key rights upon
87       entering a signal handler if the desired rights  differ  from  the  de‐
88       faults.   The  rights  of any interrupted context are restored when the
89       signal handler returns.
90
91       This signal behavior is unusual and is due to the  fact  that  the  x86
92       PKRU  register  (which  stores protection key access rights) is managed
93       with the same hardware mechanism (XSAVE)  that  manages  floating-point
94       registers.   The  signal behavior is the same as that of floating-point
95       registers.
96
97   Protection Keys system calls
98       The Linux kernel implements the following  pkey-related  system  calls:
99       pkey_mprotect(2), pkey_alloc(2), and pkey_free(2).
100
101       The  Linux  pkey system calls are available only if the kernel was con‐
102       figured and built with the CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS  op‐
103       tion.
104

EXAMPLES

106       The  program  below allocates a page of memory with read and write per‐
107       missions.  It then writes some data  to  the  memory  and  successfully
108       reads  it  back.   After that, it attempts to allocate a protection key
109       and disallows access to the page by using the WRPKRU  instruction.   It
110       then  tries  to  access  the page, which we now expect to cause a fatal
111       signal to the application.
112
113           $ ./a.out
114           buffer contains: 73
115           about to read buffer again...
116           Segmentation fault (core dumped)
117
118   Program source
119
120       #define _GNU_SOURCE
121       #include <err.h>
122       #include <unistd.h>
123       #include <stdio.h>
124       #include <stdlib.h>
125       #include <sys/mman.h>
126
127       int
128       main(void)
129       {
130           int status;
131           int pkey;
132           int *buffer;
133
134           /*
135            * Allocate one page of memory.
136            */
137           buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE,
138                         MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
139           if (buffer == MAP_FAILED)
140               err(EXIT_FAILURE, "mmap");
141
142           /*
143            * Put some random data into the page (still OK to touch).
144            */
145           *buffer = __LINE__;
146           printf("buffer contains: %d\n", *buffer);
147
148           /*
149            * Allocate a protection key:
150            */
151           pkey = pkey_alloc(0, 0);
152           if (pkey == -1)
153               err(EXIT_FAILURE, "pkey_alloc");
154
155           /*
156            * Disable access to any memory with "pkey" set,
157            * even though there is none right now.
158            */
159           status = pkey_set(pkey, PKEY_DISABLE_ACCESS);
160           if (status)
161               err(EXIT_FAILURE, "pkey_set");
162
163           /*
164            * Set the protection key on "buffer".
165            * Note that it is still read/write as far as mprotect() is
166            * concerned and the previous pkey_set() overrides it.
167            */
168           status = pkey_mprotect(buffer, getpagesize(),
169                                  PROT_READ | PROT_WRITE, pkey);
170           if (status == -1)
171               err(EXIT_FAILURE, "pkey_mprotect");
172
173           printf("about to read buffer again...\n");
174
175           /*
176            * This will crash, because we have disallowed access.
177            */
178           printf("buffer contains: %d\n", *buffer);
179
180           status = pkey_free(pkey);
181           if (status == -1)
182               err(EXIT_FAILURE, "pkey_free");
183
184           exit(EXIT_SUCCESS);
185       }
186

SEE ALSO

188       pkey_alloc(2), pkey_free(2), pkey_mprotect(2), sigaction(2)
189
190
191
192Linux man-pages 6.04              2022-10-30                          pkeys(7)
Impressum