| Message ID | 1590614258-24728-6-git-send-email-Dave.Martin@arm.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | prctl.2 man page updates for Linux 5.6 | expand |
On Wed, May 27, 2020 at 10:17:37PM +0100, Dave Martin wrote: > Add documentation for the PR_PAC_RESET_KEYS ioctl added in Linux > 5.0 for arm64. [...] > +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. I might be misreading this, but this looks like the kernel reference appears mid-sentence. Regardless, I think we should drop the kernel doc reference, as I mentioned on the SVE patches. With that: Acked-by: Will Deacon <will@kernel.org> Will
Hi Will, Thanks for reviewing. On 6/9/20 12:02 PM, Will Deacon wrote: > On Wed, May 27, 2020 at 10:17:37PM +0100, Dave Martin wrote: >> Add documentation for the PR_PAC_RESET_KEYS ioctl added in Linux >> 5.0 for arm64. > > [...] > >> +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. > > I might be misreading this, but this looks like the kernel reference appears > mid-sentence. It's hidden as a comment (.\"). > Regardless, I think we should drop the kernel doc reference, > as I mentioned on the SVE patches. I actually request that people add these kinds of comments in the source. It helps me verify details in patches, and is also handy when checking details in the future. > With that: > > Acked-by: Will Deacon <will@kernel.org> Thanks. Cheers, Michael
Hello Dave, I've applied this patch (manually, because 4/6 is not yet applied). I have a question below. On 5/27/20 11:17 PM, Dave Martin wrote: > 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(+) > [...] > +.IP > +.B Warning: > +Because the compiler or run-time environment > +may be using some or all of the keys, > +a successful Things got a bit garbled here. I think the next few lines should have been at the end. > +.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. I applied the following change after your patch; is it okay? .IP .B Warning: Because the compiler or run-time environment may be using some or all of the keys, a successful +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. .IP For more information, see the kernel source file .I Documentation/arm64/pointer\-authentication.rst @@ -1020,9 +1023,6 @@ For more information, see the kernel source file .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)" [...] Thanks, Michael
On Tue, Jun 09, 2020 at 01:36:42PM +0200, Michael Kerrisk (man-pages) wrote: > Hello Dave, > > I've applied this patch (manually, because 4/6 is not yet applied). > I have a question below. > > On 5/27/20 11:17 PM, Dave Martin wrote: > > 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(+) > > > > [...] > > > +.IP > > +.B Warning: > > +Because the compiler or run-time environment > > +may be using some or all of the keys, > > +a successful > > Things got a bit garbled here. I think the next few lines should have been > at the end. > > +.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. > > I applied the following change after your patch; is it okay? > > .IP > .B Warning: > Because the compiler or run-time environment > may be using some or all of the keys, > a successful Looks fine, execpt that I think you need to move the .B PR_PAC_RESET_KEYS line here also. Thanks ---Dave > +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. > .IP > For more information, see the kernel source file > .I Documentation/arm64/pointer\-authentication.rst > @@ -1020,9 +1023,6 @@ For more information, see the kernel source file > .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)" > [...]
>> I applied the following change after your patch; is it okay? >> >> .IP >> .B Warning: >> Because the compiler or run-time environment >> may be using some or all of the keys, >> a successful > > Looks fine, execpt that I think you need to move the > > .B PR_PAC_RESET_KEYS > > line here also. Thanks. Fixed. But, the fix will be in the 5.08 man-pages release, I'm sorry. I cut 5.07 a few hours ago. Cheers, Michael
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.
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(+)