diff options
Diffstat (limited to 'man7/pkeys.7')
| -rw-r--r-- | man7/pkeys.7 | 237 |
1 files changed, 0 insertions, 237 deletions
diff --git a/man7/pkeys.7 b/man7/pkeys.7 deleted file mode 100644 index 4fb814c99..000000000 --- a/man7/pkeys.7 +++ /dev/null @@ -1,237 +0,0 @@ -.\" 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) |