| 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) |