1 .. SPDX-License-Identifier: GPL-2.0
2
3 ======================
4 Memory Protection Keys
5 ======================
6
7 Memory Protection Keys provide a mechanism for
8 protections, but without requiring modificatio
9 application changes protection domains.
10
11 Pkeys Userspace (PKU) is a feature which can b
12 * Intel server CPUs, Skylake and later
13 * Intel client CPUs, Tiger Lake (11th
14 * Future AMD CPUs
15
16 Pkeys work by dedicating 4 previously Reserved
17 a "protection key", giving 16 possible keys.
18
19 Protections for each key are defined with a pe
20 (PKRU). Each of these is a 32-bit register st
21 and Write Disable) for each of 16 keys.
22
23 Being a CPU register, PKRU is inherently threa
24 thread a different set of protections from eve
25
26 There are two instructions (RDPKRU/WRPKRU) for
27 register. The feature is only available in 64
28 theoretically space in the PAE PTEs. These pe
29 access only and have no effect on instruction
30
31 Syscalls
32 ========
33
34 There are 3 system calls which directly intera
35
36 int pkey_alloc(unsigned long flags, un
37 int pkey_free(int pkey);
38 int pkey_mprotect(unsigned long start,
39 unsigned long prot,
40
41 Before a pkey can be used, it must first be al
42 pkey_alloc(). An application calls the WRPKRU
43 directly in order to change access permissions
44 with a key. In this example WRPKRU is wrapped
45 called pkey_set().
46 ::
47
48 int real_prot = PROT_READ|PROT_WRITE;
49 pkey = pkey_alloc(0, PKEY_DISABLE_WRIT
50 ptr = mmap(NULL, PAGE_SIZE, PROT_NONE,
51 ret = pkey_mprotect(ptr, PAGE_SIZE, re
52 ... application runs here
53
54 Now, if the application needs to update the da
55 gain access, do the update, then remove its wr
56
57 pkey_set(pkey, 0); // clear PKEY_DISAB
58 *ptr = foo; // assign something
59 pkey_set(pkey, PKEY_DISABLE_WRITE); //
60
61 Now when it frees the memory, it will also fre
62 is no longer in use::
63
64 munmap(ptr, PAGE_SIZE);
65 pkey_free(pkey);
66
67 .. note:: pkey_set() is a wrapper for the RDPK
68 An example implementation can be fou
69 tools/testing/selftests/x86/protecti
70
71 Behavior
72 ========
73
74 The kernel attempts to make protection keys co
75 behavior of a plain mprotect(). For instance
76
77 mprotect(ptr, size, PROT_NONE);
78 something(ptr);
79
80 you can expect the same effects with protectio
81
82 pkey = pkey_alloc(0, PKEY_DISABLE_WRIT
83 pkey_mprotect(ptr, size, PROT_READ|PRO
84 something(ptr);
85
86 That should be true whether something() is a d
87 like::
88
89 *ptr = foo;
90
91 or when the kernel does the access on the appl
92 with a read()::
93
94 read(fd, ptr, 1);
95
96 The kernel will send a SIGSEGV in both cases,
97 to SEGV_PKERR when violating protection keys v
98 the plain mprotect() permissions are violated.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.