pkru(3) man page.
Reviewed by: alc, markj, jilles With more input from: pho Sponsored by: The FreeBSD Foundation MFC after: 2 weeks Differential revision: https://reviews.freebsd.org/D19211
This commit is contained in:
kib
parent
9b75be29f4
commit
bab8ff3145
@ -6,6 +6,9 @@ SRCS+= \
|
||||
__vdso_gettc.c \
|
||||
pkru.c
|
||||
|
||||
MAN+= \
|
||||
pkru.3
|
||||
|
||||
.if ${MACHINE_CPUARCH} == "amd64" && ${MK_HYPERV} != "no"
|
||||
CFLAGS+= -DWANT_HYPERV
|
||||
.endif
|
||||
|
||||
206
lib/libc/x86/sys/pkru.3
Normal file
206
lib/libc/x86/sys/pkru.3
Normal file
@ -0,0 +1,206 @@
|
||||
.\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
|
||||
.\" All rights reserved.
|
||||
.\"
|
||||
.\" This documentation was written by
|
||||
.\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
|
||||
.\" from the FreeBSD Foundation.
|
||||
.\"
|
||||
.\" Redistribution and use in source and binary forms, with or without
|
||||
.\" modification, are permitted provided that the following conditions
|
||||
.\" are met:
|
||||
.\" 1. Redistributions of source code must retain the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer.
|
||||
.\" 2. Redistributions in binary form must reproduce the above copyright
|
||||
.\" notice, this list of conditions and the following disclaimer in the
|
||||
.\" documentation and/or other materials provided with the distribution.
|
||||
.\"
|
||||
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
|
||||
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
||||
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
||||
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
|
||||
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
||||
.\" SUCH DAMAGE.
|
||||
.\"
|
||||
.\" $FreeBSD$
|
||||
.\"
|
||||
.Dd February 16, 2019
|
||||
.Dt PKRU 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm Protection Key Rights for User pages
|
||||
.Nd provide fast user-managed key-based access control for pages
|
||||
.Sh LIBRARY
|
||||
.Lb libc
|
||||
.Sh SYNOPSIS
|
||||
.In machine/sysarch.h
|
||||
.Ft int
|
||||
.Fn x86_pkru_get_perm "unsigned int keyidx" "int *access" "int *modify"
|
||||
.Ft int
|
||||
.Fn x86_pkru_set_perm "unsigned int keyidx" "int access" "int modify"
|
||||
.Ft int
|
||||
.Fo x86_pkru_protect_range
|
||||
.Fa "void *addr"
|
||||
.Fa "unsigned long len"
|
||||
.Fa "unsigned int keyidx"
|
||||
.Fa "int flag"
|
||||
.Fc
|
||||
.Ft int
|
||||
.Fn x86_pkru_unprotect_range "void *addr" "unsigned long len"
|
||||
.Sh DESCRIPTION
|
||||
The protection keys feature provides an additional mechanism, besides the
|
||||
normal page permissions as established by
|
||||
.Xr mmap 2
|
||||
and
|
||||
.Xr mprotect 2 ,
|
||||
to control access to user-mode addresses.
|
||||
The mechanism gives safety measures which can be used to avoid
|
||||
incidental read or modification of sensitive memory,
|
||||
or as a debugging feature.
|
||||
It cannot guard against conscious accesses since permissions
|
||||
are user-controllable.
|
||||
.Pp
|
||||
If supported by hardware, each mapped user linear address
|
||||
has an associated 4-bit protection key.
|
||||
A new per-thread PKRU hardware register determines, for each protection
|
||||
key, whether user-mode addresses with that protection key may be
|
||||
read or written.
|
||||
.Pp
|
||||
Only one key may apply to a given range at a time.
|
||||
The default protection key index is zero, it is used even if no key
|
||||
was explicitly assigned to the address, or if the key was removed.
|
||||
.Pp
|
||||
The protection prevents the system from accessing user addresses as well
|
||||
as the user applications.
|
||||
When a system call was unable to read or write user memory due to key
|
||||
protection, it returns the
|
||||
.Er EFAULT
|
||||
error code.
|
||||
Note that some side effects may have occurred if this error is reported.
|
||||
.Pp
|
||||
Protection keys require that the system uses 4-level paging
|
||||
(also called long mode),
|
||||
which means that it is only available on amd64 system.
|
||||
Both 64-bit and 32-bit applications can use protection keys.
|
||||
More information about the hardware feature is provided in the IA32 Software
|
||||
Developer's Manual published by Intel Corp.
|
||||
.Pp
|
||||
The key indexes written into the page table entries are managed by the
|
||||
.Fn sysarch
|
||||
syscall.
|
||||
Per-key permissions are managed using the user-mode instructions
|
||||
.Em RDPKRU
|
||||
and
|
||||
.Em WRPKRU.
|
||||
The system provides convenient library helpers for both the syscall and
|
||||
the instructions, described below.
|
||||
.Pp
|
||||
The
|
||||
.Fn x86_pkru_protect_range
|
||||
function assigns key
|
||||
.Fa keyidx
|
||||
to the range starting at
|
||||
.Fa addr
|
||||
and having length
|
||||
.Fa len .
|
||||
Starting address is truncated to the page start,
|
||||
and the end is rounded up to the end of the page.
|
||||
After a successfull call, the range has the specified key assigned,
|
||||
even if the key is zero and it did not change the page table entries.
|
||||
.Pp
|
||||
The
|
||||
.Fa flags
|
||||
argument takes the logical OR of the following values:
|
||||
.Bl -tag -width
|
||||
.It Bq Va AMD64_PKRU_EXCL
|
||||
Only assign the key if the range does not have any other keys assigned
|
||||
(including the zero key).
|
||||
You must first remove any existing key with
|
||||
.Fn x86_pkru_unprotect_range
|
||||
in order for this request to succeed.
|
||||
If the
|
||||
.Va AMD64_PKRU_EXCL
|
||||
flag is not specified,
|
||||
.Fn x86_pkru_protect_range
|
||||
replaces any existing key.
|
||||
.It Bq Va AMD64_PKRU_PERSIST
|
||||
The keys assigned to the range are persistent.
|
||||
They are re-established when the current mapping is destroyed
|
||||
and a new mapping is created in any sub-range of the specified range.
|
||||
You must use a
|
||||
.Fn x86_pkru_unprotect_range
|
||||
call to forget the key.
|
||||
.El
|
||||
.Pp
|
||||
The
|
||||
.Fn x86_pkru_unprotect_range
|
||||
function removes any keys assigned to the specified range.
|
||||
Existing mappings are changed to use key index zero in page table entries.
|
||||
Keys are no longer considered installed for all mappings in the range,
|
||||
for the purposes of
|
||||
.Fn x86_pkru_protect_range
|
||||
with the
|
||||
.Va AMD64_PKRU_EXCL
|
||||
flag.
|
||||
.Pp
|
||||
The
|
||||
.Fn x86_pkru_get_perm
|
||||
function returns access rights for the key specified by the
|
||||
.Fn keyidx
|
||||
argument.
|
||||
If the value pointed to by
|
||||
.Fa access
|
||||
is zero after the call, no read or write permissions is granted for
|
||||
mappings which are assigned the key
|
||||
.Fn keyidx .
|
||||
If
|
||||
.Fa access
|
||||
is not zero, read access is permitted.
|
||||
The non-zero value of the variable pointed to by the
|
||||
.Fa modify
|
||||
argument indicates that write access is permitted.
|
||||
.Pp
|
||||
Conversely, the
|
||||
.Fn x86_pkru_set_perm
|
||||
establishes the access and modify permissions for the given key index
|
||||
as specified by its arguments.
|
||||
.Sh RETURN VALUES
|
||||
.Rv -std
|
||||
.Sh ERRORS
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EOPNOTSUPP
|
||||
The hardware does not support protection keys.
|
||||
.It Bq Er EINVAL
|
||||
The supplied key index is invalid (greater than 15).
|
||||
.It Bq Er EINVAL
|
||||
The supplied
|
||||
.Fa flags
|
||||
argument for
|
||||
.Fn x86_pkru_protect_range
|
||||
has reserved bits set.
|
||||
.It Bq Er EFAULT
|
||||
The supplied address range does not completely fit into the user-managed
|
||||
address range.
|
||||
.It Bq Er ENOMEM
|
||||
The memory shortage prevents the completion of the operation.
|
||||
.It Bq Er EBUSY
|
||||
The
|
||||
.Va AMD64_PKRU_EXCL
|
||||
flag was specified for
|
||||
.Fn x86_pkru_protect_range
|
||||
and the range already has defined protection keys.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr mmap 2 ,
|
||||
.Xr mprotect 2 ,
|
||||
.Xr munmap 2 ,
|
||||
.Xr sysarch 2 .
|
||||
.Sh STANDARDS
|
||||
The
|
||||
.Nm
|
||||
functions are non-standard and first appeared in
|
||||
.Fx 13.0 .
|
||||
Loading…
Reference in New Issue
Block a user