[PATCH v2 5/6] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

[Dave Martin <Dave.Martin@arm.com>]

Add documentation for the PR_PAC_RESET_KEYS ioctl added in Linux
5.0 for arm64.

Signed-off-by: Dave Martin <Dave.Martin@arm.com>
Cc: Will Deacon <will@kernel.org>
Cc: Catalin Marinas <catalin.marinas@arm.com>
Cc: Amit Daniel Kachhap <amit.kachhap@arm.com>
Cc: Mark Rutland <mark.rutland@arm.com>

---

Since v1:

 * Clarify explicitly that PR_PAC_RESET_KEYS is redundant when combined
   with execve().

 * Move error condition details into the prctl description, to avoid
   excessive duplication while keeping keeping related pieces of text
   closer together.

 * In lieu of having a separate man page to cross reference for detailed
   guidance, cross-reference the kernel documentation.

 * Add safety warning.  This is deliberately vague, pending ongoing
   discussions with libc folks.
---
 man2/prctl.2 | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index 91df7c8..3ee2702 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -950,6 +950,77 @@ behavior.
 A value of 1 indicates
 .BR execve (2)
 will operate in the privilege-restricting mode described above.
+.\" 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 \(lqA\(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
+.BR 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,
+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
+.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).
+.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.
 .\" prctl PR_SET_PDEATHSIG
 .TP
 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
@@ -1964,6 +2035,15 @@ are not 0.
 .B EINVAL
 .I option
 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 option
+is
 .B PR_SVE_SET_VL
 and the arguments are invalid or unsupported,
 or SVE is not available on this platform.
-- 
2.1.4