1 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc. 2 .\" All rights reserved. 3 .\" 4 .\" This documentation was written by 5 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship 6 .\" from the FreeBSD Foundation. 7 .\" 8 .\" Redistribution and use in source and binary forms, with or without 9 .\" modification, are permitted provided that the following conditions 10 .\" are met: 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. 16 .\" 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 27 .\" SUCH DAMAGE. 28 .\" 29 .\" $FreeBSD$ 30 .\" 31 .Dd February 16, 2019 32 .Dt PKRU 3 33 .Os 34 .Sh NAME 35 .Nm Protection Key Rights for User pages 36 .Nd provide fast user-managed key-based access control for pages 37 .Sh LIBRARY 38 .Lb libc 39 .Sh SYNOPSIS 40 .In machine/sysarch.h 41 .Ft int 42 .Fn x86_pkru_get_perm "unsigned int keyidx" "int *access" "int *modify" 43 .Ft int 44 .Fn x86_pkru_set_perm "unsigned int keyidx" "int access" "int modify" 45 .Ft int 46 .Fo x86_pkru_protect_range 47 .Fa "void *addr" 48 .Fa "unsigned long len" 49 .Fa "unsigned int keyidx" 50 .Fa "int flag" 51 .Fc 52 .Ft int 53 .Fn x86_pkru_unprotect_range "void *addr" "unsigned long len" 54 .Sh DESCRIPTION 55The protection keys feature provides an additional mechanism, besides the 56normal page permissions as established by 57 .Xr mmap 2 58and 59 .Xr mprotect 2 , 60to control access to user-mode addresses. 61The mechanism gives safety measures which can be used to avoid 62incidental read or modification of sensitive memory, 63or as a debugging feature. 64It cannot guard against conscious accesses since permissions 65are user-controllable. 66 .Pp 67If supported by hardware, each mapped user linear address 68has an associated 4-bit protection key. 69A new per-thread PKRU hardware register determines, for each protection 70key, whether user-mode addresses with that protection key may be 71read or written. 72 .Pp 73Only one key may apply to a given range at a time. 74The default protection key index is zero, it is used even if no key 75was explicitly assigned to the address, or if the key was removed. 76 .Pp 77The protection prevents the system from accessing user addresses as well 78as the user applications. 79When a system call was unable to read or write user memory due to key 80protection, it returns the 81 .Er EFAULT 82error code. 83Note that some side effects may have occurred if this error is reported. 84 .Pp 85Protection keys require that the system uses 4-level paging 86(also called long mode), 87which means that it is only available on amd64 system. 88Both 64-bit and 32-bit applications can use protection keys. 89More information about the hardware feature is provided in the IA32 Software 90Developer's Manual published by Intel Corp. 91 .Pp 92The key indexes written into the page table entries are managed by the 93 .Fn sysarch 94syscall. 95Per-key permissions are managed using the user-mode instructions 96 .Em RDPKRU 97and 98 .Em WRPKRU . 99The system provides convenient library helpers for both the syscall and 100the instructions, described below. 101 .Pp 102The 103 .Fn x86_pkru_protect_range 104function assigns key 105 .Fa keyidx 106to the range starting at 107 .Fa addr 108and having length 109 .Fa len . 110Starting address is truncated to the page start, 111and the end is rounded up to the end of the page. 112After a successfull call, the range has the specified key assigned, 113even if the key is zero and it did not change the page table entries. 114 .Pp 115The 116 .Fa flags 117argument takes the logical OR of the following values: 118 .Bl -tag -width 119 .It Bq Va AMD64_PKRU_EXCL 120Only assign the key if the range does not have any other keys assigned 121(including the zero key). 122You must first remove any existing key with 123 .Fn x86_pkru_unprotect_range 124in order for this request to succeed. 125If the 126 .Va AMD64_PKRU_EXCL 127flag is not specified, 128 .Fn x86_pkru_protect_range 129replaces any existing key. 130 .It Bq Va AMD64_PKRU_PERSIST 131The keys assigned to the range are persistent. 132They are re-established when the current mapping is destroyed 133and a new mapping is created in any sub-range of the specified range. 134You must use a 135 .Fn x86_pkru_unprotect_range 136call to forget the key. 137 .El 138 .Pp 139The 140 .Fn x86_pkru_unprotect_range 141function removes any keys assigned to the specified range. 142Existing mappings are changed to use key index zero in page table entries. 143Keys are no longer considered installed for all mappings in the range, 144for the purposes of 145 .Fn x86_pkru_protect_range 146with the 147 .Va AMD64_PKRU_EXCL 148flag. 149 .Pp 150The 151 .Fn x86_pkru_get_perm 152function returns access rights for the key specified by the 153 .Fn keyidx 154argument. 155If the value pointed to by 156 .Fa access 157is zero after the call, no read or write permissions is granted for 158mappings which are assigned the key 159 .Fn keyidx . 160If 161 .Fa access 162is not zero, read access is permitted. 163The non-zero value of the variable pointed to by the 164 .Fa modify 165argument indicates that write access is permitted. 166 .Pp 167Conversely, the 168 .Fn x86_pkru_set_perm 169establishes the access and modify permissions for the given key index 170as specified by its arguments. 171 .Sh RETURN VALUES 172 .Rv -std 173 .Sh ERRORS 174 .Bl -tag -width Er 175 .It Bq Er EOPNOTSUPP 176The hardware does not support protection keys. 177 .It Bq Er EINVAL 178The supplied key index is invalid (greater than 15). 179 .It Bq Er EINVAL 180The supplied 181 .Fa flags 182argument for 183 .Fn x86_pkru_protect_range 184has reserved bits set. 185 .It Bq Er EFAULT 186The supplied address range does not completely fit into the user-managed 187address range. 188 .It Bq Er ENOMEM 189The memory shortage prevents the completion of the operation. 190 .It Bq Er EBUSY 191The 192 .Va AMD64_PKRU_EXCL 193flag was specified for 194 .Fn x86_pkru_protect_range 195and the range already has defined protection keys. 196 .El 197 .Sh SEE ALSO 198 .Xr mmap 2 , 199 .Xr mprotect 2 , 200 .Xr munmap 2 , 201 .Xr sysarch 2 . 202 .Sh STANDARDS 203The 204 .Nm 205functions are non-standard and first appeared in 206 .Fx 13.0 . 207