diff options
Diffstat (limited to 'man/man7/pkeys.7')
| -rw-r--r-- | man/man7/pkeys.7 | 237 |
1 files changed, 237 insertions, 0 deletions
diff --git a/man/man7/pkeys.7 b/man/man7/pkeys.7 new file mode 100644 index 000000000..4fb814c99 --- /dev/null +++ b/man/man7/pkeys.7 @@ -0,0 +1,237 @@ +.\" Copyright (C) 2016 Intel Corporation +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH pkeys 7 (date) "Linux man-pages (unreleased)" +.SH NAME +pkeys \- overview of Memory Protection Keys +.SH DESCRIPTION +Memory Protection Keys (pkeys) are an extension to existing +page-based memory permissions. +Normal page permissions using +page tables require expensive system calls and TLB invalidations +when changing permissions. +Memory Protection Keys provide a mechanism for changing +protections without requiring modification of the page tables on +every permission change. +.P +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. +.P +Protection keys work in conjunction with the existing +.BR PROT_READ , +.BR PROT_WRITE , +and +.B PROT_EXEC +permissions passed to system calls such as +.BR mprotect (2) +and +.BR mmap (2), +but always act to further restrict these traditional permission +mechanisms. +.P +If a process performs an access that violates pkey +restrictions, it receives a +.B SIGSEGV +signal. +See +.BR sigaction (2) +for details of the information available with that signal. +.P +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, +and this hardware supports 16 protection keys in each process. +However, pkey 0 is used as the default key, so a maximum of 15 +are available for actual application use. +The default key is assigned to any memory region for which a +pkey has not been explicitly assigned via +.BR pkey_mprotect (2). +.P +Protection keys have the potential to add a layer of security and +reliability to applications. +But they have not been primarily designed as +a security feature. +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. +.P +Applications should be very careful to ensure that they do not "leak" +protection keys. +For instance, before calling +.BR pkey_free (2), +the application should be sure that no memory has that pkey assigned. +If the application left the freed pkey assigned, a future user of +that pkey might inadvertently change the permissions of an unrelated +data structure, which could impact security or stability. +The kernel currently allows in-use pkeys to have +.BR pkey_free (2) +called on them because it would have processor or memory performance +implications to perform the additional checks needed to disallow it. +Implementation of the necessary checks is left up to applications. +Applications may implement these checks by searching the +.IR /proc/ pid /smaps +file for memory regions with the pkey assigned. +Further details can be found in +.BR proc (5). +.P +Any application wanting to use protection keys needs to be able +to function without them. +They might be unavailable because the hardware that the +application runs on does not support them, the kernel code does +not contain support, the kernel support has been disabled, or +because the keys have all been allocated, perhaps by a library +the application is using. +It is recommended that applications wanting to use protection +keys should simply call +.BR pkey_alloc (2) +and test whether the call succeeds, +instead of attempting to detect support for the +feature in any other way. +.P +Although unnecessary, hardware support for protection keys may be +enumerated with the +.I cpuid +instruction. +Details of how to do this can be found in the Intel Software +Developers Manual. +The kernel performs this enumeration and exposes the information in +.I /proc/cpuinfo +under the "flags" field. +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. +.P +Applications using threads and protection keys should be especially +careful. +Threads inherit the protection key rights of the parent at the time +of the +.BR clone (2), +system call. +Applications should either ensure that their own permissions are +appropriate for child threads at the time when +.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. +.P +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). +.P +The Linux pkey system calls are available only if the kernel was +configured and built with the +.B CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS +option. +.SH EXAMPLES +The program below allocates a page of memory with read and write permissions. +It then writes some data to the memory and successfully reads it +back. +After that, it attempts to allocate a protection key and +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. +.P +.in +4n +.EX +.RB "$" " ./a.out" +buffer contains: 73 +about to read buffer again... +Segmentation fault (core dumped) +.EE +.in +.SS Program source +\& +.EX +#define _GNU_SOURCE +#include <err.h> +#include <unistd.h> +#include <stdio.h> +#include <stdlib.h> +#include <sys/mman.h> +\& +int +main(void) +{ + int status; + int pkey; + int *buffer; +\& + /* + * Allocate one page of memory. + */ + buffer = mmap(NULL, getpagesize(), PROT_READ | PROT_WRITE, + MAP_ANONYMOUS | MAP_PRIVATE, \-1, 0); + if (buffer == MAP_FAILED) + err(EXIT_FAILURE, "mmap"); +\& + /* + * Put some random data into the page (still OK to touch). + */ + *buffer = __LINE__; + printf("buffer contains: %d\en", *buffer); +\& + /* + * Allocate a protection key: + */ + pkey = pkey_alloc(0, 0); + if (pkey == \-1) + err(EXIT_FAILURE, "pkey_alloc"); +\& + /* + * Disable access to any memory with "pkey" set, + * even though there is none right now. + */ + status = pkey_set(pkey, PKEY_DISABLE_ACCESS); + if (status) + err(EXIT_FAILURE, "pkey_set"); +\& + /* + * Set the protection key on "buffer". + * Note that it is still read/write as far as mprotect() is + * concerned and the previous pkey_set() overrides it. + */ + status = pkey_mprotect(buffer, getpagesize(), + PROT_READ | PROT_WRITE, pkey); + if (status == \-1) + err(EXIT_FAILURE, "pkey_mprotect"); +\& + printf("about to read buffer again...\en"); +\& + /* + * This will crash, because we have disallowed access. + */ + printf("buffer contains: %d\en", *buffer); +\& + status = pkey_free(pkey); + if (status == \-1) + err(EXIT_FAILURE, "pkey_free"); +\& + exit(EXIT_SUCCESS); +} +.EE +.SH SEE ALSO +.BR pkey_alloc (2), +.BR pkey_free (2), +.BR pkey_mprotect (2), +.BR sigaction (2) |