From: Dave Martin <Dave.Martin@arm.com>
To: Michael Kerrisk <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 v2 5/6] prctl.2: Add PR_PAC_RESET_KEYS (arm64)
Date: Wed, 27 May 2020 22:17:37 +0100 [thread overview]
Message-ID: <1590614258-24728-6-git-send-email-Dave.Martin@arm.com> (raw)
In-Reply-To: <1590614258-24728-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>
---
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
next prev parent reply other threads:[~2020-05-27 21:18 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
2020-05-27 21:17 [PATCH v2 0/6] prctl.2 man page updates for Linux 5.6 Dave Martin
2020-05-27 21:17 ` [PATCH v2 1/6] prctl.2: ffix use literal hyphens when referencing kernel docs Dave Martin
2020-05-28 6:05 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [PATCH v2 2/6] prctl.2: Add PR_SPEC_INDIRECT_BRANCH for SPECULATION_CTRL prctls Dave Martin
2020-05-28 7:01 ` Michael Kerrisk (man-pages)
2020-06-01 13:51 ` Dave Martin
2020-06-09 11:00 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [PATCH v2 3/6] prctl.2: Add PR_SPEC_DISABLE_NOEXEC " Dave Martin
2020-05-28 6:57 ` Michael Kerrisk (man-pages)
2020-05-28 13:45 ` Waiman Long
2020-05-27 21:17 ` [PATCH v2 4/6] prctl.2: Add SVE prctls (arm64) Dave Martin
2020-06-09 9:57 ` Will Deacon
2020-06-09 14:11 ` Dave Martin
2020-06-09 14:49 ` Will Deacon
2020-06-10 9:44 ` Dave Martin
2020-06-09 11:39 ` Michael Kerrisk (man-pages)
2020-06-10 9:45 ` Dave Martin
2020-05-27 21:17 ` Dave Martin [this message]
2020-06-09 10:02 ` [PATCH v2 5/6] prctl.2: Add PR_PAC_RESET_KEYS (arm64) Will Deacon
2020-06-09 11:03 ` Michael Kerrisk (man-pages)
2020-06-09 11:36 ` Michael Kerrisk (man-pages)
2020-06-09 14:16 ` Dave Martin
2020-06-09 18:11 ` Michael Kerrisk (man-pages)
2020-05-27 21:17 ` [RFC PATCH v2 6/6] prctl.2: Add tagged address ABI control prctls (arm64) Dave Martin
2020-06-09 11:04 ` Michael Kerrisk (man-pages)
2020-06-09 13:38 ` Will Deacon
2020-06-09 17:22 ` Catalin Marinas
2020-06-10 10:06 ` Dave Martin
2020-06-10 15:26 ` Catalin Marinas
2020-06-10 16:42 ` Dave Martin
2020-06-10 17:42 ` Catalin Marinas
2020-06-15 14:51 ` Dave Martin
2020-06-24 9:54 ` Michael Kerrisk (man-pages)
2020-06-24 10:29 ` Dave Martin
2020-05-28 7:11 ` [PATCH v2 0/6] prctl.2 man page updates for Linux 5.6 Michael Kerrisk (man-pages)
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=1590614258-24728-6-git-send-email-Dave.Martin@arm.com \
--to=dave.martin@arm.com \
--cc=amit.kachhap@arm.com \
--cc=catalin.marinas@arm.com \
--cc=linux-arch@vger.kernel.org \
--cc=linux-arm-kernel@lists.infradead.org \
--cc=linux-man@vger.kernel.org \
--cc=mark.rutland@arm.com \
--cc=mtk.manpages@gmail.com \
--cc=will@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).