.\" Copyright, the authors of the Linux man-pages project
.\"
.\" 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
.BR "#include <linux/prctl.h>" "  /* Definition of " PR_* " constants */"
.B #include <sys/prctl.h>
.P
.BI "int prctl(PR_PAC_RESET_KEYS, unsigned long " keys ", 0L, 0L, 0L);"
.fi
.SH DESCRIPTION
Securely reset the thread's pointer authentication keys
to fresh random values generated by the kernel.
.P
The set of keys to be reset is specified by
.IR keys ,
which must be a logical OR of zero or more of the following:
.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.)
.P
As a special case, if
.I keys
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.
.P
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.
.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 keys
contains set bits that are invalid or unsupported on this platform.
.SH STANDARDS
Linux.
arm64 only.
.SH HISTORY
Linux 5.0 (arm64).
.\" commit ba830885656414101b2f8ca88786524d4bb5e8c1
.SH CAVEATS
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.
.SH SEE ALSO
.BR prctl (2)
.P
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).