[PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)

From: Dave Martin <Dave.Martin@arm.com>
To: mtk.manpages@gmail.com
Cc: linux-man@vger.kernel.org, linux-arch@vger.kernel.org,
	linux-arm-kernel@lists.infradead.org,
	Will Deacon <will@kernel.org>,
	Catalin Marinas <catalin.marinas@arm.com>,
	Amit Daniel Kachhap <amit.kachhap@arm.com>,
	Mark Rutland <mark.rutland@arm.com>
Subject: [PATCH 14/14] prctl.2: Add PR_PAC_RESET_KEYS (arm64)
Date: Tue, 12 May 2020 17:36:59 +0100	[thread overview]
Message-ID: <1589301419-24459-15-git-send-email-Dave.Martin@arm.com> (raw)
In-Reply-To: <1589301419-24459-1-git-send-email-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>

---

Note that the comment about PR_PAC_RESET_KEYS(0) being the recommended
way to set up a fresh execution context is not present in the existing
kernel documentation.

I vaguely remember some discussion to this effect; in any case, it seems
sensible, given that there must have been _some_ rationale for this
feature...  Shout if it sounds wrong!
---
 man2/prctl.2 | 61 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)

diff --git a/man2/prctl.2 b/man2/prctl.2
index dd16227..7ea60e2 100644
--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -950,6 +950,46 @@ 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 creating a new execution context.
+.IP
+The remaining arguments
+.IR arg3 ", " arg4 " and " arg5
+must all be zero.
 .\" prctl PR_SET_PDEATHSIG
 .TP
 .BR PR_SET_PDEATHSIG " (since Linux 2.1.57)"
@@ -1920,6 +1960,27 @@ are not 0.
 .B EINVAL
 .I option
 was
+.B PR_PAC_RESET_KEYS
+and
+.I arg2
+contains non-zero bits other than
+.BR
+.BR PR_PAC_APIAKEY ,
+.BR PR_PAC_APIBKEY ,
+.BR PR_PAC_APDAKEY ,
+.B PR_PAC_APDBKEY
+and
+.BR PR_PAC_APGAKEY ;
+or
+.IR arg3 ,
+.I arg4
+and
+.I arg5
+were not all zero.
+.TP
+.B EINVAL
+.I option
+was
 .B PR_SVE_SET_VL
 and
 .I arg2
-- 
2.1.4

