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

2 files changed, 209 insertions, 0 deletions

diff --git a/lib/libc/x86/sys/Makefile.inc b/lib/libc/x86/sys/Makefile.inc
index 640fbf02c21b..41e0d1a8ad66 100644
--- a/lib/libc/x86/sys/Makefile.inc
+++ b/lib/libc/x86/sys/Makefile.inc
@@ -6,6 +6,9 @@ SRCS+= \
 	__vdso_gettc.c \
 	pkru.c
 
+MAN+=	\
+	pkru.3
+
 .if ${MACHINE_CPUARCH} == "amd64" && ${MK_HYPERV} != "no"
 CFLAGS+=	-DWANT_HYPERV
 .endif
diff --git a/lib/libc/x86/sys/pkru.3 b/lib/libc/x86/sys/pkru.3
new file mode 100644
index 000000000000..4ebf155b9274
--- /dev/null
+++ b/lib/libc/x86/sys/pkru.3
@@ -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 .