1 .. SPDX-License-Identifier: GPL-2.0 2 3 ====================== 4 Memory Protection Keys 5 ====================== 6 7 Memory Protection Keys provide a mechanism for enforcing page-based 8 protections, but without requiring modification of the page tables when an 9 application changes protection domains. 10 11 Pkeys Userspace (PKU) is a feature which can be found on: 12 * Intel server CPUs, Skylake and later 13 * Intel client CPUs, Tiger Lake (11th Gen Core) and later 14 * Future AMD CPUs 15 * arm64 CPUs implementing the Permission Overlay Extension (FEAT_S1POE) 16 17 x86_64 18 ====== 19 Pkeys work by dedicating 4 previously Reserved bits in each page table entry to 20 a "protection key", giving 16 possible keys. 21 22 Protections for each key are defined with a per-CPU user-accessible register 23 (PKRU). Each of these is a 32-bit register storing two bits (Access Disable 24 and Write Disable) for each of 16 keys. 25 26 Being a CPU register, PKRU is inherently thread-local, potentially giving each 27 thread a different set of protections from every other thread. 28 29 There are two instructions (RDPKRU/WRPKRU) for reading and writing to the 30 register. The feature is only available in 64-bit mode, even though there is 31 theoretically space in the PAE PTEs. These permissions are enforced on data 32 access only and have no effect on instruction fetches. 33 34 arm64 35 ===== 36 37 Pkeys use 3 bits in each page table entry, to encode a "protection key index", 38 giving 8 possible keys. 39 40 Protections for each key are defined with a per-CPU user-writable system 41 register (POR_EL0). This is a 64-bit register encoding read, write and execute 42 overlay permissions for each protection key index. 43 44 Being a CPU register, POR_EL0 is inherently thread-local, potentially giving 45 each thread a different set of protections from every other thread. 46 47 Unlike x86_64, the protection key permissions also apply to instruction 48 fetches. 49 50 Syscalls 51 ======== 52 53 There are 3 system calls which directly interact with pkeys:: 54 55 int pkey_alloc(unsigned long flags, unsigned long init_access_rights) 56 int pkey_free(int pkey); 57 int pkey_mprotect(unsigned long start, size_t len, 58 unsigned long prot, int pkey); 59 60 Before a pkey can be used, it must first be allocated with pkey_alloc(). An 61 application writes to the architecture specific CPU register directly in order 62 to change access permissions to memory covered with a key. In this example 63 this is wrapped by a C function called pkey_set(). 64 :: 65 66 int real_prot = PROT_READ|PROT_WRITE; 67 pkey = pkey_alloc(0, PKEY_DISABLE_WRITE); 68 ptr = mmap(NULL, PAGE_SIZE, PROT_NONE, MAP_ANONYMOUS|MAP_PRIVATE, -1, 0); 69 ret = pkey_mprotect(ptr, PAGE_SIZE, real_prot, pkey); 70 ... application runs here 71 72 Now, if the application needs to update the data at 'ptr', it can 73 gain access, do the update, then remove its write access:: 74 75 pkey_set(pkey, 0); // clear PKEY_DISABLE_WRITE 76 *ptr = foo; // assign something 77 pkey_set(pkey, PKEY_DISABLE_WRITE); // set PKEY_DISABLE_WRITE again 78 79 Now when it frees the memory, it will also free the pkey since it 80 is no longer in use:: 81 82 munmap(ptr, PAGE_SIZE); 83 pkey_free(pkey); 84 85 .. note:: pkey_set() is a wrapper around writing to the CPU register. 86 Example implementations can be found in 87 tools/testing/selftests/mm/pkey-{arm64,powerpc,x86}.h 88 89 Behavior 90 ======== 91 92 The kernel attempts to make protection keys consistent with the 93 behavior of a plain mprotect(). For instance if you do this:: 94 95 mprotect(ptr, size, PROT_NONE); 96 something(ptr); 97 98 you can expect the same effects with protection keys when doing this:: 99 100 pkey = pkey_alloc(0, PKEY_DISABLE_WRITE | PKEY_DISABLE_READ); 101 pkey_mprotect(ptr, size, PROT_READ|PROT_WRITE, pkey); 102 something(ptr); 103 104 That should be true whether something() is a direct access to 'ptr' 105 like:: 106 107 *ptr = foo; 108 109 or when the kernel does the access on the application's behalf like 110 with a read():: 111 112 read(fd, ptr, 1); 113 114 The kernel will send a SIGSEGV in both cases, but si_code will be set 115 to SEGV_PKERR when violating protection keys versus SEGV_ACCERR when 116 the plain mprotect() permissions are violated. 117 118 Note that kernel accesses from a kthread (such as io_uring) will use a default 119 value for the protection key register and so will not be consistent with 120 userspace's value of the register or mprotect(). 121