1 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
2 .\" All rights reserved.
4 .\" This documentation was written by
5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
6 .\" from the FreeBSD Foundation.
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nm Protection Key Rights for User pages
36 .Nd provide fast user-managed key-based access control for pages
42 .Fn x86_pkru_get_perm "unsigned int keyidx" "int *access" "int *modify"
44 .Fn x86_pkru_set_perm "unsigned int keyidx" "int access" "int modify"
46 .Fo x86_pkru_protect_range
48 .Fa "unsigned long len"
49 .Fa "unsigned int keyidx"
53 .Fn x86_pkru_unprotect_range "void *addr" "unsigned long len"
55 The protection keys feature provides an additional mechanism, besides the
56 normal page permissions as established by
60 to control access to user-mode addresses.
61 The mechanism gives safety measures which can be used to avoid
62 incidental read or modification of sensitive memory,
63 or as a debugging feature.
64 It cannot guard against conscious accesses since permissions
65 are user-controllable.
67 If supported by hardware, each mapped user linear address
68 has an associated 4-bit protection key.
69 A new per-thread PKRU hardware register determines, for each protection
70 key, whether user-mode addresses with that protection key may be
73 Only one key may apply to a given range at a time.
74 The default protection key index is zero, it is used even if no key
75 was explicitly assigned to the address, or if the key was removed.
77 The protection prevents the system from accessing user addresses as well
78 as the user applications.
79 When a system call was unable to read or write user memory due to key
80 protection, it returns the
83 Note that some side effects may have occurred if this error is reported.
85 Protection keys require that the system uses 4-level paging
86 (also called long mode),
87 which means that it is only available on amd64 system.
88 Both 64-bit and 32-bit applications can use protection keys.
89 More information about the hardware feature is provided in the IA32 Software
90 Developer's Manual published by Intel Corp.
92 The key indexes written into the page table entries are managed by the
95 Per-key permissions are managed using the user-mode instructions
99 The system provides convenient library helpers for both the syscall and
100 the instructions, described below.
103 .Fn x86_pkru_protect_range
106 to the range starting at
110 Starting address is truncated to the page start,
111 and the end is rounded up to the end of the page.
112 After a successfull call, the range has the specified key assigned,
113 even if the key is zero and it did not change the page table entries.
117 argument takes the logical OR of the following values:
119 .It Bq Va AMD64_PKRU_EXCL
120 Only assign the key if the range does not have any other keys assigned
121 (including the zero key).
122 You must first remove any existing key with
123 .Fn x86_pkru_unprotect_range
124 in order for this request to succeed.
127 flag is not specified,
128 .Fn x86_pkru_protect_range
129 replaces any existing key.
130 .It Bq Va AMD64_PKRU_PERSIST
131 The keys assigned to the range are persistent.
132 They are re-established when the current mapping is destroyed
133 and a new mapping is created in any sub-range of the specified range.
135 .Fn x86_pkru_unprotect_range
136 call to forget the key.
140 .Fn x86_pkru_unprotect_range
141 function removes any keys assigned to the specified range.
142 Existing mappings are changed to use key index zero in page table entries.
143 Keys are no longer considered installed for all mappings in the range,
145 .Fn x86_pkru_protect_range
151 .Fn x86_pkru_get_perm
152 function returns access rights for the key specified by the
155 If the value pointed to by
157 is zero after the call, no read or write permissions is granted for
158 mappings which are assigned the key
162 is not zero, read access is permitted.
163 The non-zero value of the variable pointed to by the
165 argument indicates that write access is permitted.
168 .Fn x86_pkru_set_perm
169 establishes the access and modify permissions for the given key index
170 as specified by its arguments.
176 The hardware does not support protection keys.
178 The supplied key index is invalid (greater than 15).
183 .Fn x86_pkru_protect_range
184 has reserved bits set.
186 The supplied address range does not completely fit into the user-managed
189 The memory shortage prevents the completion of the operation.
193 flag was specified for
194 .Fn x86_pkru_protect_range
195 and the range already has defined protection keys.
205 functions are non-standard and first appeared in