.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
-.TH PKEYS 7 2016-03-03 "Linux" "Linux Programmer's Manual"
+.TH PKEYS 7 2019-03-06 "Linux" "Linux Programmer's Manual"
.SH NAME
pkeys \- overview of Memory Protection Keys
.SH DESCRIPTION
Memory Protection Keys provide a mechanism for changing
protections without requiring modification of the page tables on
every permission change.
-
+.PP
To use pkeys, software must first "tag" a page in the page tables
with a pkey.
After this tag is in place, an application only has
to change the contents of a register in order to remove write
access, or all access to a tagged page.
-
+.PP
Protection keys work in conjunction with the existing
-.BR PROT_READ /
+.BR PROT_READ /
.BR PROT_WRITE /
.BR PROT_EXEC
permissions passed to system calls such as
.BR mmap (2),
but always act to further restrict these traditional permission
mechanisms.
-
+.PP
If a process performs an access that violates pkey
restrictions, it receives a
.BR SIGSEGV
See
.BR sigaction (2)
for details of the information available with that signal.
-
+.PP
To use the pkeys feature, the processor must support it, and the kernel
must contain support for the feature on a given processor.
As of early 2016 only future Intel x86 processors are supported,
The default key is assigned to any memory region for which a
pkey has not been explicitly assigned via
.BR pkey_mprotect (2).
-
+.PP
Protection keys have the potential to add a layer of security and
reliability to applications.
But they have not been primarily designed as
For instance, WRPKRU is a completely unprivileged
instruction, so pkeys are useless in any case that an attacker controls
the PKRU register or can execute arbitrary instructions.
-
+.PP
Applications should be very careful to ensure that they do not "leak"
protection keys.
For instance, before calling
file for memory regions with the pkey assigned.
Further details can be found in
.BR proc (5).
-
+.PP
Any application wanting to use protection keys needs to be able
to function without them.
They might be unavailable because the hardware that the
and test whether the call succeeds,
instead of attempting to detect support for the
feature in any other way.
-
+.PP
Although unnecessary, hardware support for protection keys may be
enumerated with the
.I cpuid
The string "pku" in this field indicates hardware support for protection
keys and the string "ospke" indicates that the kernel contains and has
enabled protection keys support.
-
+.PP
Applications using threads and protection keys should be especially
careful.
Threads inherit the protection key rights of the parent at the time
.BR clone (2)
is called, or ensure that each child thread can perform its
own initialization of protection key rights.
+.\"
+.SS Signal Handler Behavior
+Each time a signal handler is invoked (including nested signals), the
+thread is temporarily given a new, default set of protection key rights
+that override the rights from the interrupted context.
+This means that applications must re-establish their desired protection
+key rights upon entering a signal handler if the desired rights differ
+from the defaults.
+The rights of any interrupted context are restored when the signal
+handler returns.
+.PP
+This signal behavior is unusual and is due to the fact that the x86 PKRU
+register (which stores protection key access rights) is managed with the
+same hardware mechanism (XSAVE) that manages floating-point registers.
+The signal behavior is the same as that of floating-point registers.
+.\"
.SS Protection Keys system calls
The Linux kernel implements the following pkey-related system calls:
.BR pkey_mprotect (2),
.BR pkey_alloc (2),
and
.BR pkey_free (2).
-
+.PP
The Linux pkey system calls are available only if the kernel was
configured and built with the
.BR CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS
disallows access to the page by using the WRPKRU instruction.
It then tries to access the page,
which we now expect to cause a fatal signal to the application.
-
+.PP
.in +4n
-.nf
+.EX
.RB "$" " ./a.out"
buffer contains: 73
about to read buffer again...
Segmentation fault (core dumped)
-.fi
+.EE
.in
.SS Program source
\&
-.nf
+.EX
#define _GNU_SOURCE
#include <unistd.h>
#include <sys/syscall.h>
unsigned int ecx = 0;
unsigned int edx = 0;
- asm volatile(".byte 0x0f,0x01,0xef\\n\\t"
+ asm volatile(".byte 0x0f,0x01,0xef\en\et"
: : "a" (eax), "c" (ecx), "d" (edx));
}
return syscall(SYS_pkey_free, pkey);
}
-#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \\
+#define errExit(msg) do { perror(msg); exit(EXIT_FAILURE); \e
} while (0)
int
* Put some random data into the page (still OK to touch)
*/
*buffer = __LINE__;
- printf("buffer contains: %d\\n", *buffer);
+ printf("buffer contains: %d\en", *buffer);
/*
* Allocate a protection key:
if (status == -1)
errExit("pkey_mprotect");
- printf("about to read buffer again...\\n");
+ printf("about to read buffer again...\en");
/*
* This will crash, because we have disallowed access
*/
- printf("buffer contains: %d\\n", *buffer);
+ printf("buffer contains: %d\en", *buffer);
status = pkey_free(pkey);
if (status == -1)
exit(EXIT_SUCCESS);
}
+.EE
.SH SEE ALSO
.BR pkey_alloc (2),
.BR pkey_free (2),
projects / thirdparty / man-pages.git / blobdiff