plucky (2) PR_PAC_RESET_KEYS.2const.gz

NAME

       PR_PAC_RESET_KEYS - reset the calling thread's pointer authentication code keys

LIBRARY

       Standard C library (libc, -lc)

SYNOPSIS

       #include <linux/prctl.h>  /* Definition of PR_* constants */
       #include <sys/prctl.h>

       int prctl(PR_PAC_RESET_KEYS, unsigned long keys, 0L, 0L, 0L);

DESCRIPTION

       Securely reset the thread's pointer authentication keys to fresh random values generated by the kernel.

       The  set  of  keys  to  be  reset is specified by keys, which must be a logical OR of zero or more of the
       following:

       PR_PAC_APIAKEY
              instruction authentication key A

       PR_PAC_APIBKEY
              instruction authentication key B

       PR_PAC_APDAKEY
              data authentication key A

       PR_PAC_APDBKEY
              data authentication key B

       PR_PAC_APGAKEY
              generic authentication “A” key.

              (Yes folks, there really is no generic B key.)

       As a special case, if keys 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.

       There is no need to use PR_PAC_RESET_KEYS in preparation for calling execve(2),  since  execve(2)  resets
       all the pointer authentication keys.

RETURN VALUE

       On success, 0 is returned.  On error, -1 is returned, and errno is set to indicate the error.

ERRORS

       EINVAL keys contains set bits that are invalid or unsupported on this platform.

STANDARDS

       Linux.  arm64 only.

HISTORY

       Linux 5.0 (arm64).

CAVEATS

       Because  the  compiler  or  run-time  environment  may  be  using  some  or all of the keys, a successful
       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.

SEE ALSO

       prctl(2)

       For  more  information,  see  the  kernel  source file Documentation/arm64/pointer-authentication.rst (or
       Documentation/arm64/pointer-authentication.txt before Linux 5.3).