# pkeys

## NAME



           pkeys - overview of Memory Protection Keys
    


## 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.
    
           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.
    
           Protection keys work in conjunction with the existing **PROT_READ** ,
           **PROT_WRITE** , and **PROT_EXEC** permissions passed to system calls such
           as mprotect(2) and mmap(2), but always act to further restrict
           these traditional permission mechanisms.
    
           If a process performs an access that violates pkey restrictions,
           it receives a **SIGSEGV** signal.  See sigaction(2) for details of the
           information available with that signal.
    
           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 pkey_mprotect(2).
    
           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.
    
           Applications should be very careful to ensure that they do not
           "leak" protection keys.  For instance, before calling
           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 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 _/proc/_ pid _/smaps_ file for
           memory regions with the pkey assigned.  Further details can be
           found in proc(5).
    
           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
           pkey_alloc(2) and test whether the call succeeds, instead of
           attempting to detect support for the feature in any other way.
    
           Although unnecessary, hardware support for protection keys may be
           enumerated with the _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
           _/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.
    
           Applications using threads and protection keys should be
           especially careful.  Threads inherit the protection key rights of
           the parent at the time of the clone(2), system call.  Applications
           should either ensure that their own permissions are appropriate
           for child threads at the time when clone(2) is called, or ensure
           that each child thread can perform its own initialization of
           protection key rights.
    
       **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.
    
           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.
    
       **Protection Keys system calls**
           The Linux kernel implements the following pkey-related system
           calls: pkey_mprotect(2), pkey_alloc(2), and pkey_free(2).
    
           The Linux pkey system calls are available only if the kernel was
           configured and built with the
           **CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS** option.
    


## 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.
    
               $ **./a.out**
               buffer contains: 73
               about to read buffer again...
               Segmentation fault (core dumped)
    
       **Program source**
    
           #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\n", *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...\n");
    
               /*
                * This will crash, because we have disallowed access.
                */
               printf("buffer contains: %d\n", *buffer);
    
               status = pkey_free(pkey);
               if (status == -1)
                   err(EXIT_FAILURE, "pkey_free");
    
               exit(EXIT_SUCCESS);
           }
    


* * *