diff options
| author | Alejandro Colomar <alx@kernel.org> | 2024-05-29 21:18:58 +0200 |
|---|---|---|
| committer | Alejandro Colomar <alx@kernel.org> | 2024-05-31 01:52:38 +0200 |
| commit | 59e741f7740ce3616c0d58b417d06f25be1cba4a (patch) | |
| tree | ef3a86cb7f80b5ddcf7f592deb21f0e748c3b346 | |
| parent | 77050d368e549d2b17eb70b5fc29e4a2bf8351b0 (diff) | |
| download | man-pages-59e741f7740ce3616c0d58b417d06f25be1cba4a.tar.gz | |
prctl.2, PR_PAC_RESET_KEYS.2const: Split PR_PAC_RESET_KEYS from prctl(2)
Signed-off-by: Alejandro Colomar <alx@kernel.org>
| -rw-r--r-- | man/man2/prctl.2 | 81 | ||||
| -rw-r--r-- | man/man2const/PR_PAC_RESET_KEYS.2const | 115 |
2 files changed, 117 insertions, 79 deletions
diff --git a/man/man2/prctl.2 b/man/man2/prctl.2 index 041f27bcf2..76e5788df2 100644 --- a/man/man2/prctl.2 +++ b/man/man2/prctl.2 @@ -112,77 +112,8 @@ The first argument can be: .B PR_SET_NO_NEW_PRIVS .TQ .B PR_GET_NO_NEW_PRIVS -.\" prctl PR_PAC_RESET_KEYS -.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1 -.TP -.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)" -Securely reset the thread's pointer authentication keys -to fresh random values generated by the kernel. -.IP -The set of keys to be reset is specified by -.IR arg2 , -which must be a logical OR of zero or more of the following: -.RS -.TP -.B PR_PAC_APIAKEY -instruction authentication key A -.TP -.B PR_PAC_APIBKEY -instruction authentication key B -.TP -.B PR_PAC_APDAKEY -data authentication key A -.TP -.B PR_PAC_APDBKEY -data authentication key B -.TP -.B PR_PAC_APGAKEY -generic authentication \[lq]A\[rq] key. -.IP -(Yes folks, there really is no generic B key.) -.RE -.IP -As a special case, if -.I arg2 -is zero, then all the keys are reset. -Since new keys could be added in future, -this is the recommended way to completely wipe the existing keys -when establishing a clean execution context. -Note that there is no need to use -.B PR_PAC_RESET_KEYS -in preparation for calling -.BR execve (2), -since -.BR execve (2) -resets all the pointer authentication keys. -.IP -The remaining arguments -.IR arg3 ", " arg4 ", and " arg5 -must all be zero. -.IP -If the arguments are invalid, -and in particular if -.I arg2 -contains set bits that are unrecognized -or that correspond to a key not available on this platform, -then the call fails with error -.BR EINVAL . -.IP -.B Warning: -Because the compiler or run-time environment -may be using some or all of the keys, -a successful +.TQ .B PR_PAC_RESET_KEYS -may crash the calling process. -The conditions for using it safely are complex and system-dependent. -Don't use it unless you know what you are doing. -.IP -For more information, see the kernel source file -.I Documentation/arm64/pointer\-authentication.rst -.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed -(or -.I Documentation/arm64/pointer\-authentication.txt -before Linux 5.3). .\" prctl PR_SET_PDEATHSIG .TP .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)" @@ -1334,15 +1265,6 @@ is not .B EINVAL .I op is -.B PR_PAC_RESET_KEYS -and the arguments are invalid or unsupported. -See the description of -.B PR_PAC_RESET_KEYS -above for details. -.TP -.B EINVAL -.I op -is .B PR_SVE_SET_VL and the arguments are invalid or unsupported, or SVE is not available on this platform. @@ -1491,4 +1413,5 @@ glibc 2.0.6 .BR PR_GET_NAME (2const), .BR PR_SET_NO_NEW_PRIVS (2const), .BR PR_GET_NO_NEW_PRIVS (2const), +.BR PR_PAC_RESET_KEYS (2const), .BR core (5) diff --git a/man/man2const/PR_PAC_RESET_KEYS.2const b/man/man2const/PR_PAC_RESET_KEYS.2const new file mode 100644 index 0000000000..2a72afebac --- /dev/null +++ b/man/man2const/PR_PAC_RESET_KEYS.2const @@ -0,0 +1,115 @@ +.\" Copyright 2020, Dave Martin <Dave.Martin@arm.com> +.\" Copyright 2020, Michael Kerrisk <mtk.manpages@gmail.com> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH PR_PAC_RESET_KEYS 2const (date) "Linux man-pages (unreleased)" +.SH NAME +PR_PAC_RESET_KEYS +\- +reset the calling thread's pointer authentication code keys +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <sys/prctl.h> +.P +.BI "int prctl(int " op ", ...);" +.fi +.SH DESCRIPTION +.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1 +.TP +.BR PR_PAC_RESET_KEYS " (since Linux 5.0, only on arm64)" +Securely reset the thread's pointer authentication keys +to fresh random values generated by the kernel. +.IP +The set of keys to be reset is specified by +.IR arg2 , +which must be a logical OR of zero or more of the following: +.RS +.TP +.B PR_PAC_APIAKEY +instruction authentication key A +.TP +.B PR_PAC_APIBKEY +instruction authentication key B +.TP +.B PR_PAC_APDAKEY +data authentication key A +.TP +.B PR_PAC_APDBKEY +data authentication key B +.TP +.B PR_PAC_APGAKEY +generic authentication \[lq]A\[rq] key. +.IP +(Yes folks, there really is no generic B key.) +.RE +.IP +As a special case, if +.I arg2 +is zero, then all the keys are reset. +Since new keys could be added in future, +this is the recommended way to completely wipe the existing keys +when establishing a clean execution context. +Note that there is no need to use +.B PR_PAC_RESET_KEYS +in preparation for calling +.BR execve (2), +since +.BR execve (2) +resets all the pointer authentication keys. +.IP +The remaining arguments +.IR arg3 ", " arg4 ", and " arg5 +must all be zero. +.IP +If the arguments are invalid, +and in particular if +.I arg2 +contains set bits that are unrecognized +or that correspond to a key not available on this platform, +then the call fails with error +.BR EINVAL . +.IP +.B Warning: +Because the compiler or run-time environment +may be using some or all of the keys, +a successful +.B PR_PAC_RESET_KEYS +may crash the calling process. +The conditions for using it safely are complex and system-dependent. +Don't use it unless you know what you are doing. +.IP +For more information, see the kernel source file +.I Documentation/arm64/pointer\-authentication.rst +.\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed +(or +.I Documentation/arm64/pointer\-authentication.txt +before Linux 5.3). +.SH RETURN VALUE +On success, +0 is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EINVAL +.I arg2 +is not a valid value. +.TP +.B EINVAL +.I op +is +.B PR_PAC_RESET_KEYS +and the arguments are invalid or unsupported. +See the description of +.B PR_PAC_RESET_KEYS +above for details. +.SH STANDARDS +Linux. +.SH HISTORY +.SH SEE ALSO +.BR prctl (2) |