Debian Codegraph @

upstream/debian-trixie/man2/PR_PAC_RESET_KEYS.2const

raw
1 .\" Copyright 2020, Dave Martin <[email protected]>
2 .\" Copyright 2020, Michael Kerrisk <[email protected]>
3 .\" Copyright 2024, Alejandro Colomar <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH PR_PAC_RESET_KEYS 2const 2024-06-01 "Linux man-pages 6.9.1"
8 .SH NAME
9 PR_PAC_RESET_KEYS
10 \-
11 reset the calling thread's pointer authentication code keys
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ", " \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/prctl.h>" " /* Definition of " PR_* " constants */"
18 .B #include <sys/prctl.h>
19 .P
20 .BI "int prctl(PR_PAC_RESET_KEYS, unsigned long " keys ", 0L, 0L, 0L);"
21 .fi
22 .SH DESCRIPTION
23 Securely reset the thread's pointer authentication keys
24 to fresh random values generated by the kernel.
25 .P
26 The set of keys to be reset is specified by
27 .IR keys ,
28 which must be a logical OR of zero or more of the following:
29 .TP
30 .B PR_PAC_APIAKEY
31 instruction authentication key A
32 .TP
33 .B PR_PAC_APIBKEY
34 instruction authentication key B
35 .TP
36 .B PR_PAC_APDAKEY
37 data authentication key A
38 .TP
39 .B PR_PAC_APDBKEY
40 data authentication key B
41 .TP
42 .B PR_PAC_APGAKEY
43 generic authentication \[lq]A\[rq] key.
44 .IP
45 (Yes folks, there really is no generic B key.)
46 .P
47 As a special case, if
48 .I keys
49 is zero, then all the keys are reset.
50 Since new keys could be added in future,
51 this is the recommended way to completely wipe the existing keys
52 when establishing a clean execution context.
53 .P
54 There is no need to use
55 .B PR_PAC_RESET_KEYS
56 in preparation for calling
57 .BR execve (2),
58 since
59 .BR execve (2)
60 resets all the pointer authentication keys.
61 .SH RETURN VALUE
62 On success,
63 0 is returned.
64 On error, \-1 is returned, and
65 .I errno
66 is set to indicate the error.
67 .SH ERRORS
68 .TP
69 .B EINVAL
70 .I keys
71 contains set bits that are invalid or unsupported on this platform.
72 .SH STANDARDS
73 Linux.
74 arm64 only.
75 .SH HISTORY
76 Linux 5.0 (arm64).
77 .\" commit ba830885656414101b2f8ca88786524d4bb5e8c1
78 .SH CAVEATS
79 Because the compiler or run-time environment
80 may be using some or all of the keys,
81 a successful
82 .B PR_PAC_RESET_KEYS
83 may crash the calling process.
84 The conditions for using it safely are complex and system-dependent.
85 Don't use it unless you know what you are doing.
86 .SH SEE ALSO
87 .BR prctl (2)
88 .P
89 For more information, see the kernel source file
90 .I Documentation/arm64/pointer\-authentication.rst
91 .\"commit b693d0b372afb39432e1c49ad7b3454855bc6bed
92 (or
93 .I Documentation/arm64/pointer\-authentication.txt
94 before Linux 5.3).