Debian Codegraph @

upstream/debian-unstable/man7/pkeys.7

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