From owner-svn-src-all@freebsd.org Wed Feb 20 10:03:04 2019 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id B985414ED888; Wed, 20 Feb 2019 10:03:04 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 54F1370397; Wed, 20 Feb 2019 10:03:04 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 0BB803DFD; Wed, 20 Feb 2019 10:03:04 +0000 (UTC) (envelope-from kib@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x1KA33VO010103; Wed, 20 Feb 2019 10:03:03 GMT (envelope-from kib@FreeBSD.org) Received: (from kib@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x1KA33li010101; Wed, 20 Feb 2019 10:03:03 GMT (envelope-from kib@FreeBSD.org) Message-Id: <201902201003.x1KA33li010101@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: kib set sender to kib@FreeBSD.org using -f From: Konstantin Belousov Date: Wed, 20 Feb 2019 10:03:03 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r344355 - head/lib/libc/x86/sys X-SVN-Group: head X-SVN-Commit-Author: kib X-SVN-Commit-Paths: head/lib/libc/x86/sys X-SVN-Commit-Revision: 344355 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 54F1370397 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.96 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.96)[-0.964,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US]; NEURAL_HAM_LONG(-1.00)[-0.999,0] X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 20 Feb 2019 10:03:05 -0000 Author: kib Date: Wed Feb 20 10:03:03 2019 New Revision: 344355 URL: https://svnweb.freebsd.org/changeset/base/344355 Log: 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 Added: head/lib/libc/x86/sys/pkru.3 (contents, props changed) Modified: head/lib/libc/x86/sys/Makefile.inc Modified: head/lib/libc/x86/sys/Makefile.inc ============================================================================== --- head/lib/libc/x86/sys/Makefile.inc Wed Feb 20 09:56:23 2019 (r344354) +++ head/lib/libc/x86/sys/Makefile.inc Wed Feb 20 10:03:03 2019 (r344355) @@ -6,6 +6,9 @@ SRCS+= \ __vdso_gettc.c \ pkru.c +MAN+= \ + pkru.3 + .if ${MACHINE_CPUARCH} == "amd64" && ${MK_HYPERV} != "no" CFLAGS+= -DWANT_HYPERV .endif Added: head/lib/libc/x86/sys/pkru.3 ============================================================================== --- /dev/null 00:00:00 1970 (empty, because file is newly added) +++ head/lib/libc/x86/sys/pkru.3 Wed Feb 20 10:03:03 2019 (r344355) @@ -0,0 +1,206 @@ +.\" Copyright (c) 2019 The FreeBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This documentation was written by +.\" Konstantin Belousov 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 .