1PKEYS(7) Linux Programmer's Manual PKEYS(7)
2
6 pkeys - overview of Memory Protection Keys
7
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 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 Protection keys work in conjunction with the existing PROT_READ/
22 PROT_WRITE/ PROT_EXEC permissions passed to system calls such as mpro‐
23 tect(2) and mmap(2), but always act to further restrict these tradi‐
24 tional permission mechanisms.
25 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 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 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 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 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 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 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 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 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 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 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
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 $ ./a.out
114 buffer contains: 73
115 about to read buffer again...
116 Segmentation fault (core dumped)
117 Program source
119 #define _GNU_SOURCE
121 #include <unistd.h>
122 #include <sys/syscall.h>
123 #include <stdio.h>
124 #include <sys/mman.h>
125 static inline void
127 wrpkru(unsigned int pkru)
128 {
129 unsigned int eax = pkru;
130 unsigned int ecx = 0;
131 unsigned int edx = 0;
132 asm volatile(".byte 0x0f,0x01,0xef\n\t"
134 : : "a" (eax), "c" (ecx), "d" (edx));
135 }
136 int
138 pkey_set(int pkey, unsigned long rights, unsigned long flags)
139 {
140 unsigned int pkru = (rights << (2 * pkey));
141 return wrpkru(pkru);
142 }
143 int
145 pkey_mprotect(void *ptr, size_t size, unsigned long orig_prot,
146 unsigned long pkey)
147 {
148 return syscall(SYS_pkey_mprotect, ptr, size, orig_prot, pkey);
149 }
150 int
152 pkey_alloc(void)
153 {
154 return syscall(SYS_pkey_alloc, 0, 0);
155 }
156 int
158 pkey_free(unsigned long pkey)
159 {
160 return syscall(SYS_pkey_free, pkey);
161 }
162 #define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \
164 } while (0)
165 int
167 main(void)
168 {
169 int status;
170 int pkey;
171 int *buffer;
172 /*
174 * Allocate one page of memory.
175 */
176 buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE,
177 MAP_ANONYMOUS | MAP_PRIVATE, -1, 0);
178 if (buffer == MAP_FAILED)
179 errExit("mmap");
180 /*
182 * Put some random data into the page (still OK to touch).
183 */
184 *buffer = __LINE__;
185 printf("buffer contains: %d\n", *buffer);
186 /*
188 * Allocate a protection key:
189 */
190 pkey = pkey_alloc();
191 if (pkey == -1)
192 errExit("pkey_alloc");
193 /*
195 * Disable access to any memory with "pkey" set,
196 * even though there is none right now.
197 */
198 status = pkey_set(pkey, PKEY_DISABLE_ACCESS, 0);
199 if (status)
200 errExit("pkey_set");
201 /*
203 * Set the protection key on "buffer".
204 * Note that it is still read/write as far as mprotect() is
205 * concerned and the previous pkey_set() overrides it.
206 */
207 status = pkey_mprotect(buffer, getpagesize(),
208 PROT_READ | PROT_WRITE, pkey);
209 if (status == -1)
210 errExit("pkey_mprotect");
211 printf("about to read buffer again...\n");
213 /*
215 * This will crash, because we have disallowed access.
216 */
217 printf("buffer contains: %d\n", *buffer);
218 status = pkey_free(pkey);
220 if (status == -1)
221 errExit("pkey_free");
222 exit(EXIT_SUCCESS);
224 }
225
227 pkey_alloc(2), pkey_free(2), pkey_mprotect(2), sigaction(2)
228
230 This page is part of release 5.12 of the Linux man-pages project. A
231 description of the project, information about reporting bugs, and the
232 latest version of this page, can be found at
233 https://www.kernel.org/doc/man-pages/.
234Linux 2021-03-22 PKEYS(7)