lib/libc/x86/sys/pkru.3

   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
  55 The protection keys feature provides an additional mechanism, besides the
  56 normal page permissions as established by
  57 .Xr mmap 2
  58 and
  59 .Xr mprotect 2 ,
  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.
  66 .Pp
  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
  71 read or written.
  72 .Pp
  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.
  76 .Pp
  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
  81 .Er EFAULT
  82 error code.
  83 Note that some side effects may have occurred if this error is reported.
  84 .Pp
  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.
  91 .Pp
  92 The key indexes written into the page table entries are managed by the
  93 .Fn sysarch
  94 syscall.
  95 Per-key permissions are managed using the user-mode instructions
  96 .Em RDPKRU
  97 and
  98 .Em WRPKRU .
  99 The system provides convenient library helpers for both the syscall and
 100 the instructions, described below.
 101 .Pp
 102 The
 103 .Fn x86_pkru_protect_range
 104 function assigns key
 105 .Fa keyidx
 106 to the range starting at
 107 .Fa addr
 108 and having length
 109 .Fa len .
 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.
 114 .Pp
 115 The
 116 .Fa flags
 117 argument takes the logical OR of the following values:
 118 .Bl -tag -width
 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.
 125 If the
 126 .Va AMD64_PKRU_EXCL
 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.
 134 You must use a
 135 .Fn x86_pkru_unprotect_range
 136 call to forget the key.
 137 .El
 138 .Pp
 139 The
 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,
 144 for the purposes of
 145 .Fn x86_pkru_protect_range
 146 with the
 147 .Va AMD64_PKRU_EXCL
 148 flag.
 149 .Pp
 150 The
 151 .Fn x86_pkru_get_perm
 152 function returns access rights for the key specified by the
 153 .Fn keyidx
 154 argument.
 155 If the value pointed to by
 156 .Fa access
 157 is zero after the call, no read or write permissions is granted for
 158 mappings which are assigned the key
 159 .Fn keyidx .
 160 If
 161 .Fa access
 162 is not zero, read access is permitted.
 163 The non-zero value of the variable pointed to by the
 164 .Fa modify
 165 argument indicates that write access is permitted.
 166 .Pp
 167 Conversely, the
 168 .Fn x86_pkru_set_perm
 169 establishes the access and modify permissions for the given key index
 170 as specified by its arguments.
 171 .Sh RETURN VALUES
 172 .Rv -std
 173 .Sh ERRORS
 174 .Bl -tag -width Er
 175 .It Bq Er EOPNOTSUPP
 176 The hardware does not support protection keys.
 177 .It Bq Er EINVAL
 178 The supplied key index is invalid (greater than 15).
 179 .It Bq Er EINVAL
 180 The supplied
 181 .Fa flags
 182 argument for
 183 .Fn x86_pkru_protect_range
 184 has reserved bits set.
 185 .It Bq Er EFAULT
 186 The supplied address range does not completely fit into the user-managed
 187 address range.
 188 .It Bq Er ENOMEM
 189 The memory shortage prevents the completion of the operation.
 190 .It Bq Er EBUSY
 191 The
 192 .Va AMD64_PKRU_EXCL
 193 flag was specified for
 194 .Fn x86_pkru_protect_range
 195 and 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
 203 The
 204 .Nm
 205 functions are non-standard and first appeared in
 206 .Fx 13.0 .