2016-10-19 10:30:46 +00:00
|
|
|
.\" Copyright (C) 2016 Michael Kerrisk <mtk.manpages@gmail.com>
|
|
|
|
.\" and Copyright (C) 2016 Eugene Syromyatnikov <evgsyr@gmail.com>
|
|
|
|
.\" A very few fragments remain from an earlier version of this page
|
|
|
|
.\" written by David Howells (dhowells@redhat.com)
|
2010-02-25 07:29:42 +00:00
|
|
|
.\"
|
2016-10-28 10:34:03 +00:00
|
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
2013-03-10 09:28:55 +00:00
|
|
|
.\" %%%LICENSE_END
|
2010-02-25 07:29:42 +00:00
|
|
|
.\"
|
add_key.2, chown.2, epoll_ctl.2, epoll_wait.2, execve.2, fcntl.2, get_mempolicy.2, getxattr.2, ioctl.2, keyctl.2, listxattr.2, mkdir.2, mknod.2, mmap.2, msync.2, nfsservctl.2, open.2, prctl.2, removexattr.2, request_key.2, sendfile.2, set_mempolicy.2, setxattr.2, shmget.2, shutdown.2, sigaction.2, syslog.2, truncate.2, umask.2, CPU_SET.3, atexit.3, bsearch.3, cmsg.3, err.3, gethostid.3, getmntent.3, getopt.3, iconv_close.3, inet_ntop.3, longjmp.3, lsearch.3, mcheck.3, on_exit.3, putpwent.3, regex.3, resolver.3, setbuf.3, setjmp.3, setlocale.3, setlogmask.3, sleep.3, strsignal.3, sysconf.3, undocumented.3, tty_ioctl.4, proc.5, resolv.conf.5, tzfile.5, aio.7, bootparam.7, capabilities.7, fanotify.7, inotify.7, ip.7, packet.7, pthreads.7, raw.7, signal.7, socket.7, unix.7, ld.so.8, nscd.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2015-05-07 06:26:32 +00:00
|
|
|
.TH KEYCTL 2 2015-05-07 Linux "Linux Key Management Calls"
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH NAME
|
intro.1, add_key.2, get_mempolicy.2, get_thread_area.2, intro.2, keyctl.2, mbind.2, request_key.2, set_thread_area.2, clock.3, cmsg.3, getcwd.3, getpw.3, intro.3, malloc.3, posix_memalign.3, shm_open.3, sleep.3, sysconf.3, intro.4, sd.4, intro.5, locale.5, slabinfo.5, intro.6, boot.7, bootparam.7, futex.7, glob.7, hier.7, intro.7, libc.7, locale.7, mq_overview.7, netlink.7, sem_overview.7, shm_overview.7, unix.7, intro.8: Global fix: Use consistent capitalization in NAME section
The line(s) in the NAME section should only use capitals
where English usage dictates that. Otherwise, use
lowercase throughout.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:29:13 +00:00
|
|
|
keyctl \- manipulate the kernel's key management facility
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
2016-10-27 07:48:53 +00:00
|
|
|
.B #include <sys/types.h>
|
2010-02-25 07:29:42 +00:00
|
|
|
.B #include <keyutils.h>
|
|
|
|
.sp
|
2016-10-20 06:37:52 +00:00
|
|
|
.BI "long keyctl(int " operation ", ...)"
|
2016-09-26 02:24:48 +00:00
|
|
|
.sp
|
2016-10-17 13:43:16 +00:00
|
|
|
.B "/* For direct call via syscall(2): */"
|
2016-09-26 02:24:48 +00:00
|
|
|
.B #include <asm/unistd.h>
|
|
|
|
.B #include <linux/keyctl.h>
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.sp
|
2016-10-20 06:37:52 +00:00
|
|
|
.BI "long syscall(__NR_keyctl, int " operation ", __kernel_ulong_t " arg2 ,
|
2016-10-17 13:35:25 +00:00
|
|
|
.BI " __kernel_ulong_t " arg3 ", __kernel_ulong_t " arg4 ,
|
|
|
|
.BI " __kernel_ulong_t " arg5 );
|
add_key.2, keyctl.2, request_key.2, offsetof.3, pthread_attr_init.3, pthread_attr_setaffinity_np.3, pthread_attr_setdetachstate.3, pthread_attr_setguardsize.3, pthread_attr_setinheritsched.3, pthread_attr_setschedparam.3, pthread_attr_setschedpolicy.3, pthread_attr_setscope.3, pthread_attr_setstackaddr.3, pthread_attr_setstacksize.3, pthread_cancel.3, pthread_cleanup_push.3, pthread_cleanup_push_defer_np.3, pthread_equal.3, pthread_exit.3, pthread_getattr_np.3, pthread_getcpuclockid.3, pthread_self.3, pthread_setaffinity_np.3, pthread_setcancelstate.3, pthread_setconcurrency.3, pthread_setschedparam.3, pthread_setschedprio.3, pthread_testcancel.3: Global formatting fix: balance .nf/.fi pairs
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-03-12 15:37:22 +00:00
|
|
|
.fi
|
2016-10-21 07:42:13 +00:00
|
|
|
|
|
|
|
No glibc wrapper is provided for this system call; see NOTES.
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
.BR keyctl ()
|
2016-10-17 13:43:16 +00:00
|
|
|
allows user-space programs to perform key manipulation.
|
|
|
|
|
|
|
|
The operation performed by
|
2016-09-26 02:24:48 +00:00
|
|
|
.BR keyctl ()
|
2016-10-17 13:43:16 +00:00
|
|
|
is determined by the value of the
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-10-17 13:43:16 +00:00
|
|
|
argument.
|
|
|
|
Each of these operations is wrapped by
|
2016-10-28 13:15:15 +00:00
|
|
|
.I libkeyutils
|
2016-10-21 09:28:02 +00:00
|
|
|
into individual functions (noted below)
|
2016-10-17 13:43:16 +00:00
|
|
|
to permit the compiler to check types.
|
|
|
|
|
|
|
|
The permitted values for
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-10-17 13:43:16 +00:00
|
|
|
are:
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_GET_KEYRING_ID " (since Linux 2.6.11)"
|
2016-10-18 14:43:27 +00:00
|
|
|
Map a special key ID to a real key ID for this process.
|
|
|
|
|
|
|
|
This operation looks up the special key whose ID is provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
(cast to
|
2016-10-18 14:43:27 +00:00
|
|
|
.IR key_serial_t )
|
2016-10-24 13:47:05 +00:00
|
|
|
and (if it is found) the ID of the corresponding real key is returned
|
|
|
|
as the function result.
|
|
|
|
The following values may be specified in
|
|
|
|
.IR arg2 :
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_THREAD_KEYRING
|
2016-10-28 11:03:00 +00:00
|
|
|
This specifies the calling thread's thread-specific keyring.
|
2016-10-24 13:47:05 +00:00
|
|
|
See
|
2016-10-31 02:34:41 +00:00
|
|
|
.BR thread-keyring (7).
|
2016-10-24 13:47:05 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_PROCESS_KEYRING
|
2016-10-28 11:03:00 +00:00
|
|
|
This specifies the caller's process-specific keyring.
|
2016-10-24 13:47:05 +00:00
|
|
|
See
|
2016-10-31 02:34:41 +00:00
|
|
|
.BR process-keyring (7).
|
2016-10-24 13:47:05 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_SESSION_KEYRING
|
2016-10-28 11:03:00 +00:00
|
|
|
This specifies the caller's session-specific keyring.
|
2016-10-24 13:47:05 +00:00
|
|
|
See
|
2016-10-31 02:34:41 +00:00
|
|
|
.BR session-keyring (7).
|
2016-10-24 13:47:05 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_USER_KEYRING
|
2016-10-28 11:03:00 +00:00
|
|
|
This specifies the caller's UID-specific keyring.
|
2016-10-24 13:47:05 +00:00
|
|
|
See
|
2016-10-31 02:34:41 +00:00
|
|
|
.BR user-keyring (7).
|
2016-10-24 13:47:05 +00:00
|
|
|
.TP
|
|
|
|
.B KEY_SPEC_USER_SESSION_KEYRING
|
2016-10-28 11:03:00 +00:00
|
|
|
This specifies the caller's UID-session keyring.
|
2016-10-24 13:47:05 +00:00
|
|
|
See
|
2016-10-31 02:34:41 +00:00
|
|
|
.BR user-session-keyring (7).
|
2016-10-28 11:03:00 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_SPEC_REQKEY_AUTH_KEY " (since Linux 2.6.16)"
|
|
|
|
.\" commit b5f545c880a2a47947ba2118b2509644ab7a2969
|
|
|
|
This specifies the authorization key created by
|
|
|
|
.BR request_key (2)
|
|
|
|
and passed to the process it spawns to generate a key.
|
2016-11-02 22:39:37 +00:00
|
|
|
This key is available only in a
|
|
|
|
.BR request-key (8)-style
|
|
|
|
program that was passed an authorization key by the kernel and
|
|
|
|
ceases to be available once the requested key has been instantiated; see
|
|
|
|
.BR request_key (2).
|
2016-10-28 11:03:00 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_SPEC_REQUESTOR_KEYRING " (since Linux 2.6.29)"
|
|
|
|
.\" commit 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
|
|
|
|
This specifies the key ID for the
|
|
|
|
.BR request_key (2)
|
|
|
|
destination keyring.
|
2016-11-02 22:39:37 +00:00
|
|
|
This keyring is available only in a
|
|
|
|
.BR request-key (8)-style
|
|
|
|
program that was passed an authorization key by the kernel and
|
|
|
|
ceases to be available once the requested key has been instantiated; see
|
|
|
|
.BR request_key (2).
|
2016-10-24 13:47:05 +00:00
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-18 14:43:27 +00:00
|
|
|
If the key specified in
|
|
|
|
.I arg2
|
|
|
|
does not exist, then a new key is created if the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-18 14:43:27 +00:00
|
|
|
.IR int )
|
|
|
|
contains a non-zero value; otherwise the operation fails with the error
|
|
|
|
.BR ENOKEY .
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" The keyctl_get_keyring_ID.3 page says that a new key
|
|
|
|
.\" "will be created *if it is appropriate to do so**. What is the
|
|
|
|
.\" determiner for appropriate?
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-17 13:43:16 +00:00
|
|
|
permission on a keyring in order for it to be found.
|
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-18 14:43:27 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_get_keyring_ID (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_JOIN_SESSION_KEYRING " (since Linux 2.6.11)"
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What is the use case for joining a new session keyring?
|
2016-10-18 15:18:18 +00:00
|
|
|
Replace the session keyring this process subscribes to with
|
|
|
|
a new session keyring.
|
|
|
|
|
|
|
|
If
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-18 15:18:18 +00:00
|
|
|
is NULL,
|
|
|
|
an anonymous keyring with the description "_ses" is created
|
|
|
|
and the process is subscribed to that keyring as its session keyring,
|
|
|
|
displacing the previous session keyring.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-18 15:18:18 +00:00
|
|
|
Otherwise,
|
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
(cast to
|
2016-10-18 15:18:18 +00:00
|
|
|
.IR "char\ *" )
|
|
|
|
is treated as the description (name) of a keyring,
|
|
|
|
and the behavior is as follows:
|
|
|
|
.RS
|
|
|
|
.IP * 3
|
|
|
|
If a keyring with a matching description exists,
|
|
|
|
the process will attempt to subscribe to that keyring if possible;
|
|
|
|
if that is not possible, an error is returned.
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" FIXME What error is returned in the above case?
|
2016-10-18 15:18:18 +00:00
|
|
|
In order to subscribe to the keyring,
|
|
|
|
the caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-18 15:18:18 +00:00
|
|
|
permission on the keyring.
|
|
|
|
.IP *
|
|
|
|
If a keyring with a matching description does not exist,
|
|
|
|
then a new keyring with that description is created,
|
|
|
|
and the process is subscribed to that keyring as its session keyring,
|
|
|
|
displacing the previous session keyring.
|
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-17 13:43:16 +00:00
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-18 15:18:18 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_join_session_keyring (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_UPDATE " (since Linux 2.6.11)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Update a key's data payload.
|
2016-10-18 15:30:47 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR key_serial_t )
|
2016-10-18 15:30:47 +00:00
|
|
|
specifies the ID of the key to be updated.
|
2016-10-17 13:43:16 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-18 15:30:47 +00:00
|
|
|
.IR "void\ *" )
|
|
|
|
points to the new payload and
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 08:44:28 +00:00
|
|
|
(cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR size_t )
|
2016-10-18 15:30:47 +00:00
|
|
|
contains the new payload size in bytes.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I write
|
2016-10-17 13:43:16 +00:00
|
|
|
permission on the key specified and the key type must support updating.
|
2016-10-18 15:30:47 +00:00
|
|
|
|
2016-10-29 09:18:51 +00:00
|
|
|
A negatively instantiated key can be positively instantiated
|
|
|
|
with this operation.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-18 15:30:47 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_update (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_REVOKE " (since Linux 2.6.11)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Revoke the key with the ID provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
(cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-24 13:56:40 +00:00
|
|
|
The key will no longer be findable,
|
|
|
|
and it will be unavailable for further operations.
|
|
|
|
Further attempts to use the key will fail with the error
|
|
|
|
.BR EKEYREVOKED .
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME Does a revoked key get garbage collected?
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-10-18 15:44:15 +00:00
|
|
|
.IR write
|
|
|
|
or
|
|
|
|
.IR setattr
|
|
|
|
permission on the key.
|
|
|
|
.\" FIXME Keys with the KEY_FLAG_KEEP bit set cause an EPERM
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" error for KEYCTL_REVOKE. Does this need to be documented?
|
|
|
|
.\" (It's not clear how KEY_FLAG_KEEP gets set.)
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-18 15:44:15 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_revoke (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_CHOWN " (since Linux 2.6.11)"
|
2016-10-19 08:52:30 +00:00
|
|
|
Change the ownership (user and group ID) of a key.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR key_serial_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
contains the key ID.
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR uid_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
contains the new user ID (or \-1 in case the user ID shouldn't be changed).
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR gid_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
contains the new group ID (or \-1 in case the group ID shouldn't be changed).
|
2016-10-19 08:52:30 +00:00
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The key must grant the caller
|
|
|
|
.I setattr
|
2016-10-17 13:42:58 +00:00
|
|
|
permission.
|
2016-10-19 08:52:30 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
For the UID to be changed, or for the GID to be changed to a group
|
2016-10-17 13:43:16 +00:00
|
|
|
the caller is not a member of, the caller must have the
|
|
|
|
.B CAP_SYS_ADMIN
|
2016-09-26 02:24:48 +00:00
|
|
|
capability (see
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR capabilities (7)).
|
2016-10-19 08:52:30 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
If the UID is to be changed, the new user must have sufficient
|
|
|
|
quota to accept the key.
|
|
|
|
The quota deduction will be removed from the old user
|
2016-10-19 08:52:30 +00:00
|
|
|
to the new user should the UID be changed.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_chown (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_SETPERM " (since Linux 2.6.11)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Change the permissions of the key with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR key_serial_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
to the permissions provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-19 09:37:45 +00:00
|
|
|
.IR key_perm_t ).
|
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The key must grant
|
|
|
|
.I setattr
|
2016-10-17 13:42:58 +00:00
|
|
|
permission to the caller.
|
2016-10-19 09:37:45 +00:00
|
|
|
|
|
|
|
If the caller doesn't have the
|
2016-10-17 13:43:16 +00:00
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability, it can change permissions only for the keys it owns.
|
2016-10-19 09:37:45 +00:00
|
|
|
(More precisely: the caller's filesystem UID must match the UID of the key.)
|
|
|
|
|
|
|
|
The permissions in
|
|
|
|
.IR arg3
|
|
|
|
specify masks of available operations
|
|
|
|
for each of the following user categories:
|
|
|
|
.RS
|
|
|
|
.TP
|
|
|
|
.IR possessor " (since Linux 2.6.14)"
|
|
|
|
.\" commit 664cceb0093b755739e56572b836a99104ee8a75
|
|
|
|
This is the permission granted to a process that possesses the key
|
|
|
|
(has it attached searchably to one of the process's keyrings);
|
|
|
|
see
|
|
|
|
.BR keyrings (7).
|
|
|
|
.TP
|
|
|
|
.IR user
|
|
|
|
This is the permission granted to a process
|
|
|
|
whose filesystem UID matches the UID of the key.
|
|
|
|
.TP
|
|
|
|
.IR group
|
|
|
|
This is the permission granted to a process
|
|
|
|
whose filesystem GID or any of its supplementary GIDs
|
|
|
|
matches the GID of the key.
|
|
|
|
.TP
|
|
|
|
.IR other
|
|
|
|
This is the permission granted to other processes
|
|
|
|
that do not match the
|
|
|
|
.IR user
|
|
|
|
and
|
|
|
|
.IR group
|
|
|
|
categories.
|
|
|
|
.RE
|
|
|
|
.IP
|
|
|
|
The
|
|
|
|
.IR user ,
|
|
|
|
.IR group ,
|
|
|
|
and
|
|
|
|
.IR other
|
|
|
|
categories are exclusive: if a process matches the
|
|
|
|
.IR user
|
|
|
|
category, it will not receive permissions granted in the
|
|
|
|
.IR group
|
|
|
|
category; if a process matches the
|
|
|
|
.I user
|
|
|
|
or
|
|
|
|
.IR group
|
|
|
|
category, then it will not receive permissions granted in the
|
|
|
|
.IR other
|
|
|
|
category.
|
|
|
|
|
|
|
|
The
|
|
|
|
.I possessor
|
|
|
|
category grants permissions that are cumulative with the grants from the
|
|
|
|
.IR user ,
|
|
|
|
.IR group ,
|
|
|
|
or
|
|
|
|
.IR other
|
|
|
|
category.
|
|
|
|
|
|
|
|
Each permission mask is eight bits in size,
|
|
|
|
with only six bits currently used.
|
2016-10-17 13:42:58 +00:00
|
|
|
The available permissions are:
|
2016-09-26 02:24:48 +00:00
|
|
|
.RS
|
2016-10-19 09:37:45 +00:00
|
|
|
.TP
|
|
|
|
.IR view
|
|
|
|
This permission allows reading attributes of a key.
|
|
|
|
|
|
|
|
This permission is required for the
|
|
|
|
.BR KEYCTL_DESCRIBE
|
|
|
|
operation.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_VIEW ,
|
|
|
|
.BR KEY_USR_VIEW ,
|
|
|
|
.BR KEY_GRP_VIEW ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_VIEW .
|
|
|
|
.TP
|
|
|
|
.IR read
|
|
|
|
This permission allows reading a key's payload.
|
|
|
|
|
|
|
|
This permission is required for the
|
|
|
|
.BR KEYCTL_READ
|
|
|
|
operation.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_READ ,
|
|
|
|
.BR KEY_USR_READ ,
|
|
|
|
.BR KEY_GRP_READ ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_READ .
|
|
|
|
.TP
|
|
|
|
.IR write
|
|
|
|
This permission allows update or instantiation of a key's payload.
|
|
|
|
For a keyring, it allows keys to be linked and unlinked from the keyring,
|
|
|
|
|
|
|
|
This permission is required for the
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_UPDATE ,
|
|
|
|
.BR KEYCTL_REVOKE ,
|
|
|
|
.BR KEYCTL_CLEAR ,
|
|
|
|
.BR KEYCTL_LINK ,
|
|
|
|
and
|
2016-10-19 09:37:45 +00:00
|
|
|
.BR KEYCTL_UNLINK
|
|
|
|
operations.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_WRITE ,
|
|
|
|
.BR KEY_USR_WRITE ,
|
|
|
|
.BR KEY_GRP_WRITE ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_WRITE .
|
|
|
|
.TP
|
|
|
|
.IR search
|
|
|
|
This permission allows keyrings to be searched and keys to be found.
|
|
|
|
Searches can recurse only into nested keyrings
|
2016-10-17 13:42:58 +00:00
|
|
|
that have search permission set.
|
2016-10-19 09:37:45 +00:00
|
|
|
|
|
|
|
This permission is required for the
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_GET_KEYRING_ID ,
|
|
|
|
.BR KEYCTL_JOIN_SESSION_KEYRING ,
|
|
|
|
.BR KEYCTL_SEARCH ,
|
|
|
|
and
|
2016-10-19 09:37:45 +00:00
|
|
|
.BR KEYCTL_INVALIDATE
|
|
|
|
operations.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_SEARCH ,
|
|
|
|
.BR KEY_USR_SEARCH ,
|
|
|
|
.BR KEY_GRP_SEARCH ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_SEARCH .
|
|
|
|
.TP
|
|
|
|
.IR link
|
|
|
|
This permission allows a key or keyring to be linked to.
|
|
|
|
|
|
|
|
This permission is required for the
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_LINK
|
|
|
|
and
|
2016-10-19 09:37:45 +00:00
|
|
|
.BR KEYCTL_SESSION_TO_PARENT
|
|
|
|
operations.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_LINK ,
|
|
|
|
.BR KEY_USR_LINK ,
|
|
|
|
.BR KEY_GRP_LINK ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_LINK .
|
|
|
|
.TP
|
|
|
|
.IR setattr " (since Linux 2.6.15)."
|
|
|
|
This permission allows a key's UID, GID, and permissions mask to be changed.
|
|
|
|
|
|
|
|
This permission is required for the
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_REVOKE ,
|
|
|
|
.BR KEYCTL_CHOWN ,
|
|
|
|
and
|
2016-10-19 09:37:45 +00:00
|
|
|
.BR KEYCTL_SETPERM
|
|
|
|
operations.
|
|
|
|
|
|
|
|
The permission bits for each category are
|
|
|
|
.BR KEY_POS_SETATTR ,
|
|
|
|
.BR KEY_USR_SETATTR ,
|
|
|
|
.BR KEY_GRP_SETATTR ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_SETATTR .
|
2016-09-26 02:24:48 +00:00
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-19 09:37:45 +00:00
|
|
|
As a convenience, the following macros are defined as masks for
|
|
|
|
all of the permission bits in each of the user categories:
|
|
|
|
.BR KEY_POS_ALL ,
|
|
|
|
.BR KEY_USR_ALL,
|
|
|
|
.BR KEY_GRP_ALL ,
|
|
|
|
and
|
|
|
|
.BR KEY_OTH_ALL .
|
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The
|
|
|
|
.IR arg4 " and " arg5
|
|
|
|
arguments are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_setperm (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_DESCRIBE " (since Linux 2.6.11)"
|
2016-10-28 13:14:48 +00:00
|
|
|
Obtain a string describing the attributes of a specified key.
|
2016-10-19 10:28:07 +00:00
|
|
|
|
|
|
|
The ID of the key to be described is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 10:28:07 +00:00
|
|
|
(cast to
|
2016-10-17 13:43:16 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-28 13:14:48 +00:00
|
|
|
The descriptive string is returned in the buffer pointed to by
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 10:28:07 +00:00
|
|
|
(cast to
|
2016-10-28 13:14:48 +00:00
|
|
|
.IR "char\ *" );
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 10:28:07 +00:00
|
|
|
(cast to
|
|
|
|
.IR size_t )
|
|
|
|
specifies the size of that buffer in bytes.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The key must grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I view
|
2016-10-17 13:42:58 +00:00
|
|
|
permission.
|
2016-10-19 10:28:07 +00:00
|
|
|
|
2016-10-28 13:14:48 +00:00
|
|
|
The returned string is null-terminated and
|
|
|
|
contains the following information about the key:
|
2016-10-19 10:28:07 +00:00
|
|
|
|
|
|
|
.in +4n
|
2016-10-28 13:14:48 +00:00
|
|
|
.IR type ; uid ; gid ; perm ; description
|
2016-10-19 10:28:07 +00:00
|
|
|
.in
|
|
|
|
|
|
|
|
In the above,
|
|
|
|
.IR type
|
|
|
|
and
|
|
|
|
.IR description
|
|
|
|
are strings,
|
|
|
|
.IR uid
|
|
|
|
and
|
|
|
|
.IR gid
|
|
|
|
are decimal strings, and
|
|
|
|
.I perm
|
|
|
|
is a hexadecimal permissions mask.
|
2016-10-28 13:14:48 +00:00
|
|
|
The descriptive string is written with the following format:
|
2016-10-19 10:28:07 +00:00
|
|
|
|
|
|
|
%s;%d;%d;%08x;%s
|
|
|
|
|
2016-10-28 13:14:48 +00:00
|
|
|
.BR "Note: the intention is that the descriptive string should"
|
2016-10-19 10:28:07 +00:00
|
|
|
.BR "be extensible in future kernel versions".
|
|
|
|
In particular, the
|
|
|
|
.IR description
|
|
|
|
field will not contain semicolons;
|
|
|
|
it should be parsed by working backwards from the end of the string
|
|
|
|
to find the last semicolon.
|
|
|
|
This allows future semicolon-delimited fields to be inserted
|
2016-10-28 13:14:48 +00:00
|
|
|
in the descriptive string in the future.
|
2016-10-19 10:28:07 +00:00
|
|
|
|
|
|
|
Writing to the buffer is attempted only when
|
|
|
|
.IR arg3
|
|
|
|
is non-NULL and the specified buffer size
|
2016-10-28 13:14:48 +00:00
|
|
|
is large enough to accept the descriptive string
|
2016-10-19 10:28:07 +00:00
|
|
|
(including the terminating null byte).
|
|
|
|
'\" Function commentary says it copies up to buflen bytes, but see the
|
2016-09-26 02:24:48 +00:00
|
|
|
'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
|
|
|
|
'\" security/keyctl.c
|
2016-10-19 10:28:07 +00:00
|
|
|
In order to determine whether the buffer size was too small,
|
|
|
|
check to see if the return value of the operation is greater than
|
|
|
|
.IR arg4 .
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_describe (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_CLEAR
|
2016-10-19 10:36:44 +00:00
|
|
|
Clear the contents of (i.e., unlink all keys from) a keyring.
|
|
|
|
|
|
|
|
The ID of the key
|
|
|
|
(which must be of keyring type)
|
|
|
|
.\" or the error ENOTDIR results
|
|
|
|
is provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 10:36:44 +00:00
|
|
|
(cast to
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-19 10:36:44 +00:00
|
|
|
.\" According to Documentation/security/keys.txt:
|
|
|
|
.\" This function can also be used to clear special kernel keyrings if they
|
|
|
|
.\" are appropriately marked if the user has CAP_SYS_ADMIN capability. The
|
|
|
|
.\" DNS resolver cache keyring is an example of this.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I write
|
2016-10-19 10:36:44 +00:00
|
|
|
permission on the keyring.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_clear (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_LINK " (since Linux 2.6.11)"
|
2016-10-19 11:07:25 +00:00
|
|
|
Create a link from a keyring to a key.
|
|
|
|
|
|
|
|
The key to be linked is specified in
|
|
|
|
.IR arg2
|
|
|
|
(cast to
|
|
|
|
.IR key_serial_t );
|
|
|
|
the keyring is specified in
|
|
|
|
.IR arg3
|
|
|
|
(cast to
|
|
|
|
.IR key_serial_t ).
|
|
|
|
|
|
|
|
If a key with the same type and description is already linked in the keyring,
|
|
|
|
then that key is displaced from the keyring.
|
|
|
|
|
|
|
|
Before creating the link,
|
|
|
|
the kernel checks the nesting of the keyrings and returns appropriate errors
|
|
|
|
if the nesting is too deep
|
|
|
|
.\" KEYRING_SEARCH_MAX_DEPTH 6
|
|
|
|
or if the link would produce a cycle.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What is the purpose of limiting the nesting to
|
|
|
|
.\" KEYRING_SEARCH_MAX_DEPTH (6)?
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I link
|
|
|
|
permission on the key being added and
|
|
|
|
.I write
|
2016-10-19 11:07:25 +00:00
|
|
|
permission on the keyring.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_link (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_UNLINK " (since Linux 2.6.11)"
|
2016-10-19 11:15:03 +00:00
|
|
|
Unlink a key from a keyring.
|
|
|
|
|
|
|
|
The ID of the key to be unlinked is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 11:15:03 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t );
|
|
|
|
the ID of the keyring from which it is to be unlinked is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 11:15:03 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t ).
|
|
|
|
|
|
|
|
If the key is not currently linked into the keyring, an error results.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I write
|
2016-10-17 13:43:16 +00:00
|
|
|
permission on the keyring from which the key is being removed.
|
|
|
|
|
2016-10-19 11:15:03 +00:00
|
|
|
If the last link to a key is removed,
|
|
|
|
then that key will be scheduled for destruction.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_unlink (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_SEARCH " (since Linux 2.6.11)"
|
2016-10-19 11:50:59 +00:00
|
|
|
Search for a key in a keyring tree,
|
|
|
|
returning its ID and optionally linking it to a specified keyring.
|
|
|
|
|
|
|
|
The tree to be searched is specified by passing
|
|
|
|
the ID of the head keyring in
|
|
|
|
.IR arg2
|
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-19 11:50:59 +00:00
|
|
|
The search is performed breadth-first and recursively.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 11:50:59 +00:00
|
|
|
and
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 11:50:59 +00:00
|
|
|
arguments specify the key to be searched for:
|
|
|
|
.I arg3
|
|
|
|
(cast as
|
|
|
|
.IR "char\ *" )
|
|
|
|
contains the key type
|
|
|
|
(a null-terminated character string up to 32 bytes in size,
|
|
|
|
including the terminating null byte), and
|
|
|
|
.I arg4
|
|
|
|
(cast as
|
|
|
|
.IR "char\ *" )
|
|
|
|
contains the description of the key
|
|
|
|
(a null-terminated character string up to 4096 bytes in size,
|
|
|
|
including the terminating null byte).
|
|
|
|
|
|
|
|
The source keyring must grant
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-19 11:50:59 +00:00
|
|
|
permission to the caller.
|
|
|
|
When performing the recursive search, only keyrings that grant the caller
|
|
|
|
.I search
|
|
|
|
permission will be searched.
|
|
|
|
Only keys with for which the caller has
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission can be found.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 11:50:59 +00:00
|
|
|
If the key is found, its ID is returned as the function result.
|
|
|
|
|
|
|
|
If the key is found and
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
2016-10-19 11:50:59 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t )
|
2016-10-19 11:50:59 +00:00
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
|
|
.BR KEYCTL_LINK ,
|
|
|
|
the key is linked into the keyring whose ID is specified in
|
|
|
|
.IR arg5 .
|
|
|
|
If the destination keyring specified in
|
|
|
|
.I arg5
|
|
|
|
already contains a link to a key that has the same type and description,
|
|
|
|
then that link will be displaced by a link to
|
|
|
|
the key found by this operation.
|
|
|
|
|
|
|
|
Instead of valid existing keyring IDs, the source
|
|
|
|
.RI ( arg2 )
|
|
|
|
and destination
|
|
|
|
.RI ( arg5 )
|
2016-10-28 11:03:00 +00:00
|
|
|
keyrings can be one of the special keyring IDs listed under
|
|
|
|
.BR KEYCTL_GET_KEYRING_ID .
|
2016-10-19 11:50:59 +00:00
|
|
|
.IP
|
2016-10-19 08:24:10 +00:00
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_search (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_READ " (since Linux 2.6.11)"
|
2016-10-19 11:57:52 +00:00
|
|
|
Read the payload data of a key.
|
|
|
|
|
|
|
|
The ID of the key whose payload is to be read is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 11:57:52 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-24 14:25:22 +00:00
|
|
|
This can be the ID of an existing key,
|
|
|
|
or any of the special key IDs listed for
|
2016-10-28 11:03:00 +00:00
|
|
|
.BR KEYCTL_GET_KEYRING_ID .
|
2016-10-24 14:25:22 +00:00
|
|
|
.\" including KEY_SPEC_REQKEY_AUTH_KEY
|
|
|
|
|
2016-10-19 11:57:52 +00:00
|
|
|
The payload is placed in the buffer pointed by
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 11:57:52 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR "char\ *" );
|
2016-10-19 11:57:52 +00:00
|
|
|
the size of that buffer must be specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 11:57:52 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR size_t ).
|
2016-10-19 11:57:52 +00:00
|
|
|
|
2016-10-24 14:25:22 +00:00
|
|
|
The returned data will be processed for presentation
|
|
|
|
according to the key type.
|
|
|
|
For example, a keyring will return an array of
|
|
|
|
.I key_serial_t
|
|
|
|
entries representing the IDs of all the keys that are linked to it.
|
|
|
|
The
|
|
|
|
.IR "user"
|
|
|
|
key type will return its data as is.
|
|
|
|
If a key type does not implement this function,
|
|
|
|
the operation fails with the error
|
|
|
|
.BR EOPNOTSUPP .
|
|
|
|
|
|
|
|
If
|
|
|
|
.I arg3
|
|
|
|
is not NULL,
|
|
|
|
as much of the payload data as will fit is copied into the buffer.
|
|
|
|
On a successful return,
|
|
|
|
the return value is always the total size of the payload data.
|
|
|
|
To determine whether the buffer was of sufficient size,
|
|
|
|
check to see that the return value is less than or equal to
|
|
|
|
the value supplied in
|
|
|
|
.IR arg4 .
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The key must either grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I read
|
2016-10-19 11:57:52 +00:00
|
|
|
permission, or grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission when searched for from the process keyrings.
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" FIXME Above, what does "searched for from the process keyrings" mean?
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_read (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_INSTANTIATE " (since Linux 2.6.11)"
|
2016-10-29 09:28:11 +00:00
|
|
|
(Positively) instantiate an uninstantiated key with a specified payload.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME Is the only use for KEYCTL_INSTANTIATE inside a
|
|
|
|
.\" request-keys(8)-style program?
|
2016-10-19 14:22:44 +00:00
|
|
|
|
|
|
|
The ID of the key to be instantiated is provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 14:22:44 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t ).
|
|
|
|
|
|
|
|
The key payload is specified in the buffer pointed to by
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 14:22:44 +00:00
|
|
|
(cast to
|
|
|
|
.IR "void\ *");
|
|
|
|
the size of that buffer is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 14:22:44 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR size_t ).
|
2016-10-19 14:22:44 +00:00
|
|
|
|
|
|
|
The payload may be a NULL pointer and the buffer size may be 0
|
2016-11-02 22:39:37 +00:00
|
|
|
if this is supported by the key type (e.g., it is a keyring).
|
2016-10-29 09:42:31 +00:00
|
|
|
|
2016-10-19 14:22:44 +00:00
|
|
|
The operation may be fail if the payload data is in the wrong format
|
|
|
|
or is otherwise invalid.
|
|
|
|
|
|
|
|
If
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
2016-10-19 14:22:44 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t )
|
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
|
|
.BR KEYCTL_LINK ,
|
|
|
|
the instantiated key is linked into the keyring whose ID specified in
|
|
|
|
.IR arg5 .
|
|
|
|
|
|
|
|
The caller must have the appropriate authorization key;
|
|
|
|
see
|
|
|
|
.BR request_key (2).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 08:24:10 +00:00
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_instantiate (3).
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:20:00 +00:00
|
|
|
.BR KEYCTL_NEGATE " (since Linux 2.6.11)"
|
2016-10-26 14:35:19 +00:00
|
|
|
Negatively instantiate an uninstantiated key.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME Is the only use for KEYCTL_NEGATE inside a
|
|
|
|
.\" request-keys(8)-style program?
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 15:00:33 +00:00
|
|
|
This operation is equivalent to the call:
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
|
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The
|
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_negate (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-09-26 02:24:48 +00:00
|
|
|
.BR KEYCTL_SET_REQKEY_KEYRING " (since Linux 2.6.13)"
|
2016-10-20 10:34:34 +00:00
|
|
|
Set the default keyring to which implicitly requested keys
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What are implicitly requested keys? In what circumstances is
|
|
|
|
.\" KEYCTL_SET_REQKEY_KEYRING useful?
|
2016-10-29 09:42:31 +00:00
|
|
|
.\"
|
|
|
|
.\" Are implicit requests just the ones that use the kernel-internal
|
|
|
|
.\" request_key() function (which is not the same as the request_key(2)
|
|
|
|
.\" system call)?
|
2016-10-28 13:34:47 +00:00
|
|
|
.\"
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" Does this operation have any effect for the request_key(2) system call?
|
2016-10-20 10:34:34 +00:00
|
|
|
will be linked for this thread, and return the previous setting.
|
|
|
|
Implicit key requests can occur when, for example, opening files
|
|
|
|
on an AFS or NFS filesystem.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
|
|
|
.IR int )
|
2016-10-20 10:34:34 +00:00
|
|
|
should contain one of the following values,
|
|
|
|
to specify the new default keyring:
|
2016-10-17 14:17:48 +00:00
|
|
|
.RS
|
2016-10-20 10:34:34 +00:00
|
|
|
.TP
|
2016-10-17 14:17:48 +00:00
|
|
|
.BR KEY_REQKEY_DEFL_NO_CHANGE
|
2016-11-02 22:39:37 +00:00
|
|
|
Don't change the default keyring.
|
|
|
|
This option is useful, since the call returns the current default keyring
|
|
|
|
(without changing it).
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_DEFAULT
|
2016-10-20 10:34:34 +00:00
|
|
|
This selects the default behaviour,
|
|
|
|
which is to use the thread-specific keyring if there is one,
|
|
|
|
otherwise the process-specific keyring if there is one,
|
|
|
|
otherwise the session keyring if there is one,
|
|
|
|
otherwise the UID-specific session keyring.
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_THREAD_KEYRING
|
2016-10-20 10:34:34 +00:00
|
|
|
Use the thread-specific keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( thread-keyring (7))
|
2016-10-20 10:34:34 +00:00
|
|
|
as the new default keyring.
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_PROCESS_KEYRING
|
2016-10-20 10:34:34 +00:00
|
|
|
Use the process-specific keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( process-keyring (7))
|
2016-10-20 10:34:34 +00:00
|
|
|
as the new default keyring.
|
|
|
|
.TP
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_SESSION_KEYRING
|
2016-10-20 10:34:34 +00:00
|
|
|
Use the session-specific keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( session-keyring (7))
|
2016-10-20 10:34:34 +00:00
|
|
|
as the new default keyring.
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_USER_KEYRING
|
2016-10-20 10:34:34 +00:00
|
|
|
Use the UID-specific keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( user-keyring (7))
|
2016-10-20 10:34:34 +00:00
|
|
|
as the new default keyring.
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
2016-10-20 10:34:34 +00:00
|
|
|
.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING
|
|
|
|
Use the UID-specific session keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( user_session-keyring (7))
|
2016-10-20 10:34:34 +00:00
|
|
|
as the new default keyring.
|
2016-10-17 14:17:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
|
2016-09-26 02:24:48 +00:00
|
|
|
'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
|
2016-10-20 10:34:34 +00:00
|
|
|
Use the requestor keyring.
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" FIXME The preceding explanation needs to be expanded.
|
2016-10-29 19:34:39 +00:00
|
|
|
.\" Is the following correct:
|
|
|
|
.\"
|
|
|
|
.\" The requestor keyring is the dest_keyring that was supplied
|
|
|
|
.\" to a call to request_key(2)?
|
2016-10-17 14:17:48 +00:00
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-20 10:34:34 +00:00
|
|
|
All other values are invalid.
|
|
|
|
.\" (including the still-unsupported KEY_REQKEY_DEFL_GROUP_KEYRING)
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
2016-10-20 10:34:34 +00:00
|
|
|
The setting controlled by this operation is inherited by the child of
|
|
|
|
.BR fork (2)
|
|
|
|
and preserved across
|
|
|
|
.BR execve (2).
|
|
|
|
|
2016-10-19 08:24:10 +00:00
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_set_reqkey_keyring (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-09-26 02:24:48 +00:00
|
|
|
.BR KEYCTL_SET_TIMEOUT " (since Linux 2.6.16)"
|
2016-10-19 15:17:39 +00:00
|
|
|
Set a timeout on a key.
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" FIXME Other than looking in /proc/keys, is there any way of
|
|
|
|
.\" discovering the timeout on a key?
|
2016-10-19 15:17:39 +00:00
|
|
|
|
|
|
|
The ID of the key is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 15:17:39 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t ).
|
|
|
|
The timeout value, in seconds from the current time,
|
|
|
|
is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 15:17:39 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR "unsigned int" ).
|
2016-11-02 22:39:37 +00:00
|
|
|
The timeout is measured against the realtime clock.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 15:17:39 +00:00
|
|
|
Specifying the timeout value as 0 clears any existing timeout on the key.
|
|
|
|
|
2016-11-02 22:39:37 +00:00
|
|
|
The
|
|
|
|
.I /proc/keys
|
|
|
|
file displays the remaining time until each key will expire.
|
|
|
|
(This is the only method of discovering the timeout on a key.)
|
|
|
|
|
2016-10-17 13:43:16 +00:00
|
|
|
The caller must either have the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I setattr
|
2016-10-19 15:17:39 +00:00
|
|
|
permission on the key
|
|
|
|
or hold an instantiation authorization token for the key (see
|
|
|
|
.BR request_key (2)).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The key and any links to the key will be
|
|
|
|
automatically garbage collected after the timeout expires.
|
2016-10-19 15:17:39 +00:00
|
|
|
Subsequent attempts to access the key will then fail with the error
|
|
|
|
.BR EKEYEXPIRED .
|
|
|
|
|
|
|
|
This operation cannot be used to set timeouts on negative, revoked,
|
|
|
|
or expired keys.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_set_timeout (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-09-26 02:24:48 +00:00
|
|
|
.BR KEYCTL_ASSUME_AUTHORITY " (since Linux 2.6.16)"
|
2016-10-20 11:23:15 +00:00
|
|
|
Assume (or divest) the authority for the calling thread
|
2016-10-26 14:33:40 +00:00
|
|
|
to instantiate a key.
|
2016-10-29 19:34:39 +00:00
|
|
|
.\" FIXME Is the only use for KEYCTL_ASSUME_AUTHORITY inside a
|
|
|
|
.\" request-keys(8)-style program?
|
2016-10-20 11:23:15 +00:00
|
|
|
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-20 11:23:15 +00:00
|
|
|
.IR key_serial_t )
|
|
|
|
specifies either a nonzero key ID to assume authority,
|
|
|
|
or the value 0 to divest authority.
|
|
|
|
|
|
|
|
If
|
|
|
|
.I arg2
|
|
|
|
is nonzero, then it specifies the ID of an uninstantiated key for which
|
|
|
|
authority is to be assumed.
|
2016-10-26 14:33:40 +00:00
|
|
|
That key can then be instantiated using one of
|
|
|
|
.BR KEYCTL_INSTANTIATE ,
|
|
|
|
.BR KEYCTL_INSTANTIATE_IOV ,
|
|
|
|
.BR KEYCTL_REJECT ,
|
|
|
|
or
|
|
|
|
.BR KEYCTL_NEGATE .
|
|
|
|
Once the key has been instantiated,
|
|
|
|
the thread is automatically divested of authority to instantiate the key.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-26 14:33:40 +00:00
|
|
|
Authority over a key can be assumed only if the calling thread has present
|
2016-10-20 11:23:15 +00:00
|
|
|
in its keyrings the authorization key that is
|
|
|
|
associated with the specified key.
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-20 11:23:15 +00:00
|
|
|
permission on the authorization key.
|
|
|
|
|
|
|
|
If the specified key has a matching authorization key,
|
|
|
|
then the ID of that key is returned.
|
2016-10-26 14:33:40 +00:00
|
|
|
The authorization key can be read
|
|
|
|
.RB ( KEYCTL_READ )
|
|
|
|
to obtain the callout information passed to
|
2016-10-20 11:23:15 +00:00
|
|
|
.BR request_key (2).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-20 11:23:15 +00:00
|
|
|
If the ID given in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-20 11:23:15 +00:00
|
|
|
is 0, then the currently assumed authority is cleared (divested),
|
|
|
|
and the value 0 is returned.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-26 14:33:40 +00:00
|
|
|
The
|
|
|
|
.BR KEYCTL_ASSUME_AUTHORITY
|
|
|
|
mechanism allows a program such as
|
|
|
|
.BR request-key (8)
|
|
|
|
to assume the necessary authority to instantiate a new uninstantiated key
|
|
|
|
that was created as a consequence of a call to
|
|
|
|
.BR request_key (2).
|
|
|
|
For further information, see
|
|
|
|
.BR request_key (2)
|
|
|
|
and the kernel source file
|
|
|
|
.IR Documentation/security/keys-request-key.txt .
|
|
|
|
|
2016-10-17 13:43:16 +00:00
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_assume_authority (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
|
2016-10-20 12:13:41 +00:00
|
|
|
.\" commit 70a5bb72b55e82fbfbf1e22cae6975fac58a1e2d
|
|
|
|
Get the LSM (Linux Security Module) security label of the specified key.
|
|
|
|
|
|
|
|
The ID of the key whose security label is to be fetched is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-20 12:13:41 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-20 12:13:41 +00:00
|
|
|
The security label (terminated by a null byte)
|
|
|
|
will be placed in the buffer pointed to by
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-20 12:13:41 +00:00
|
|
|
.IR "char\ *" );
|
|
|
|
the size of the buffer must be provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-20 12:13:41 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR size_t ).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-20 12:13:41 +00:00
|
|
|
If
|
|
|
|
.I arg3
|
|
|
|
is specified as NULL or the buffer size specified in
|
|
|
|
.IR arg4
|
|
|
|
is too small, the full size of the security label string
|
|
|
|
(including the terminating null byte)
|
|
|
|
is returned as the function result,
|
|
|
|
and nothing is copied to the buffer.
|
|
|
|
|
|
|
|
The caller must have
|
|
|
|
.I view
|
|
|
|
permission on the specified key.
|
|
|
|
|
|
|
|
The returned security label string will be rendered in a form appropriate
|
|
|
|
to the LSM in force.
|
2016-10-29 19:34:39 +00:00
|
|
|
For example, with SELinux, it may look like:
|
2016-10-20 12:13:41 +00:00
|
|
|
|
|
|
|
unconfined_u:unconfined_r:unconfined_t:s0-s0:c0.c1023
|
|
|
|
|
|
|
|
If no LSM is currently in force,
|
|
|
|
then an empty string is placed in the buffer.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
2016-10-20 12:13:41 +00:00
|
|
|
via the functions
|
2016-10-19 08:24:10 +00:00
|
|
|
.BR keyctl_get_security (3)
|
|
|
|
and
|
|
|
|
.BR keyctl_get_security_alloc (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
|
2016-10-20 12:36:37 +00:00
|
|
|
.\" commit ee18d64c1f632043a02e6f5ba5e045bb26a5465f
|
|
|
|
Replace the session keyring to which the
|
|
|
|
.I parent
|
|
|
|
of the calling process
|
|
|
|
subscribes with the session keyring of the calling process.
|
2016-11-02 22:39:37 +00:00
|
|
|
.\" What is the use case for KEYCTL_SESSION_TO_PARENT?
|
|
|
|
.\" David Howells: the Process Authentication Groups people requested this,
|
|
|
|
.\" but then didn't use it; maybe there are no users.
|
2016-10-20 12:36:37 +00:00
|
|
|
|
|
|
|
The keyring will be replaced in the parent process at the point
|
|
|
|
where the parent next transitions from kernel space to user space.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The keyring must exist and must grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I link
|
2016-10-20 12:36:37 +00:00
|
|
|
permission.
|
|
|
|
The parent process must be single-threaded and have
|
2016-10-17 13:43:16 +00:00
|
|
|
the same effective ownership as this process
|
|
|
|
and must not be be set-user-ID or set-group-ID.
|
2016-10-20 12:36:37 +00:00
|
|
|
The UID of the parent process's existing session keyring (f it has one),
|
|
|
|
as well as the UID of the caller's session keyring
|
|
|
|
much match the caller's effective UID.
|
|
|
|
|
|
|
|
The fact that it is the parent process that is affected by this operation
|
|
|
|
allows a program such as the shell to start a child process that
|
|
|
|
uses this operation to change the shell's session keyring.
|
|
|
|
(This is what the
|
|
|
|
.BR keyctl (1)
|
|
|
|
.B new_session
|
|
|
|
command does.)
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg2 ,
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_session_to_parent (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
|
2016-10-19 14:57:52 +00:00
|
|
|
.\" commit fdd1b94581782a2ddf9124414e5b7a5f48ce2f9c
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME We need some text here on why it is useful to negatively
|
|
|
|
.\" instantiate a key
|
2016-10-19 14:57:52 +00:00
|
|
|
Mark a key as negatively instantiated and set an expiration timer
|
|
|
|
on the key.
|
|
|
|
This operation provides a superset of the functionality of the earlier
|
|
|
|
.BR KEYCTL_NEGATE
|
|
|
|
operation.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME Is the only use for KEYCTL_REJECT inside a
|
|
|
|
.\" request-keys(8)-style program?
|
2016-10-19 14:57:52 +00:00
|
|
|
|
|
|
|
The ID of the key that is to be negatively instantiated is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 14:57:52 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t ).
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-19 14:57:52 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR "unsigned int" )
|
2016-10-19 14:57:52 +00:00
|
|
|
argument specifies the lifetime of the key, in seconds.
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
2016-10-19 14:57:52 +00:00
|
|
|
.IR "unsigned int" )
|
|
|
|
specifies the error to be returned when a search hits this key;
|
|
|
|
typically, this is one of
|
|
|
|
.BR EKEYREJECTED ,
|
|
|
|
.BR EKEYREVOKED ,
|
|
|
|
or
|
|
|
|
.BR EKEYEXPIRED .
|
|
|
|
|
|
|
|
If
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
2016-10-19 14:57:52 +00:00
|
|
|
(cast to
|
|
|
|
.IR key_serial_t )
|
|
|
|
is nonzero, then, subject to the same constraints and rules as
|
|
|
|
.BR KEYCTL_LINK ,
|
|
|
|
the negatively instantiated key is linked into the keyring
|
|
|
|
whose ID specified in
|
|
|
|
.IR arg5 .
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The caller must have the appropriate instantiation permit set
|
2016-10-17 13:43:16 +00:00
|
|
|
(authorization key, see
|
|
|
|
.B KEYCTL_ASSUME_AUTHORITY
|
2016-10-19 14:57:52 +00:00
|
|
|
command and
|
|
|
|
.BR request_key (2)).
|
2016-10-17 15:35:13 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
Negative keys are used to rate limit repeated
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR request_key (2)
|
2016-09-26 02:24:48 +00:00
|
|
|
calls by causing them to return the error specified until the negative key
|
|
|
|
expires.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_reject (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
|
2016-10-19 15:31:40 +00:00
|
|
|
.\" commit ee009e4a0d4555ed522a631bae9896399674f063
|
2016-10-26 14:35:19 +00:00
|
|
|
Instantiate an uninstantiated key with a payload specified
|
2016-10-19 14:37:44 +00:00
|
|
|
via a vector of buffers.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 14:37:44 +00:00
|
|
|
This operation is the same as
|
|
|
|
.BR KEYCTL_INSTANTIATE ,
|
|
|
|
but the payload data is specified as an array of
|
|
|
|
.IR iovec
|
|
|
|
structures:
|
|
|
|
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
struct iovec {
|
|
|
|
void *iov_base; /* Starting address of buffer */
|
|
|
|
size_t iov_len; /* Size of buffer (in bytes) */
|
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
|
|
|
|
The pointer to the payload vector is specified in
|
|
|
|
.IR arg3
|
|
|
|
(cast as
|
|
|
|
.IR "const struct iovec\ *" ).
|
|
|
|
The number of items in the vector is specified in
|
|
|
|
.IR arg4
|
|
|
|
(cast as
|
|
|
|
.IR "unsigned int" ).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-10-19 14:37:44 +00:00
|
|
|
.I arg2
|
|
|
|
(key ID)
|
|
|
|
and
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
2016-10-19 14:37:44 +00:00
|
|
|
(keyring ID)
|
|
|
|
are interpreted as for
|
|
|
|
.BR KEYCTL_INSTANTIATE .
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_instantiate_iov (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
|
2016-10-19 15:31:40 +00:00
|
|
|
.\" commit fd75815f727f157a05f4c96b5294a4617c0557da
|
|
|
|
Mark a key as invalid.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What is the difference between revoking a key and invalidating a key?
|
2016-10-19 15:31:40 +00:00
|
|
|
|
|
|
|
The ID of the key to be invalidated is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 15:31:40 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-19 15:31:40 +00:00
|
|
|
To invalidate a key,
|
|
|
|
the caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-19 15:31:40 +00:00
|
|
|
permission on the key.
|
|
|
|
.\" CAP_SYS_ADMIN is permitted to invalidate certain special keys
|
|
|
|
|
|
|
|
This operation immediately marks the key as invalid
|
|
|
|
and schedules garbage collection.
|
|
|
|
The garbage collector removes the invalidated key from all keyrings and
|
|
|
|
deletes the key when its reference count reaches zero.
|
|
|
|
After this operation,
|
|
|
|
the key will be ignored by all searches,
|
|
|
|
even if it is not yet deleted.
|
|
|
|
|
|
|
|
Keys that are marked invalid become invisible to normal key operations
|
|
|
|
immediately, though they are still visible in
|
|
|
|
.I /proc/keys
|
|
|
|
(marked with an 'i' flag)
|
|
|
|
until they are actually removed.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_invalidate (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
|
2016-10-20 12:55:49 +00:00
|
|
|
.\" commit f36f8c75ae2e7d4da34f4c908cebdb4aa42c977e
|
|
|
|
Get the persistent keyring
|
2016-10-31 02:34:41 +00:00
|
|
|
.RB ( persistent-keyring (7))
|
2016-10-20 12:55:49 +00:00
|
|
|
for a specified user and link it to a specified keyring.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What is the difference between the user keyring and
|
|
|
|
.\" the persistent keyring?
|
|
|
|
.\"
|
|
|
|
.\" FIXME What is the lifetime of the persistent keyring?
|
|
|
|
.\"
|
|
|
|
.\" FIXME The session-keyring(7) page has the following text.
|
|
|
|
.\" What are the circumstances that dictate the choice?
|
|
|
|
.\"
|
|
|
|
.\" If a process doesn't have a session keyring
|
|
|
|
.\" when it is accessed, then, under certain
|
|
|
|
.\" circumstances, the user session keyring
|
|
|
|
.\" will be attached as the session keyring and
|
|
|
|
.\" under others a new session keyring will be
|
|
|
|
.\" created.
|
2016-10-20 12:55:49 +00:00
|
|
|
|
|
|
|
The user ID is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-19 08:44:28 +00:00
|
|
|
(cast to
|
2016-10-20 12:55:49 +00:00
|
|
|
.IR uid_t ).
|
|
|
|
If the value \-1 is specified, the caller's real user ID is used.
|
|
|
|
The ID of the destination keyring is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-20 12:55:49 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR key_serial_t ).
|
2016-10-20 12:55:49 +00:00
|
|
|
|
|
|
|
The caller must have the
|
|
|
|
.BR CAP_SETUID
|
|
|
|
capability in its user namespace in order to fetch the persistent keyring
|
|
|
|
for a user ID that does not match either the real or effective user ID
|
|
|
|
of the caller.
|
|
|
|
|
|
|
|
If the call is successful,
|
|
|
|
a link to the persistent keyring is added to the keyring
|
|
|
|
whose ID was specified in
|
|
|
|
.IR arg3 .
|
|
|
|
|
|
|
|
The caller must have
|
|
|
|
.I write
|
|
|
|
permission on the keyring.
|
|
|
|
|
|
|
|
The persistent keyring will be created by the kernel
|
|
|
|
if it does not yet exist.
|
|
|
|
|
|
|
|
Each time the
|
|
|
|
.B KEYCTL_GET_PERSISTENT
|
|
|
|
operation is performed, the persistent keyring will
|
|
|
|
have its expiration timeout reset to the value in:
|
|
|
|
|
|
|
|
/proc/sys/kernel/keys/persistent_keyring_expiry
|
|
|
|
|
|
|
|
Should the timeout be reached,
|
|
|
|
the persistent keyring will be removed and
|
|
|
|
everything it pins can then be garbage collected.
|
|
|
|
|
|
|
|
Persistent keyrings were added to Linux in kernel version 3.13.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2016-10-19 08:24:10 +00:00
|
|
|
|
|
|
|
This operation is exposed by
|
|
|
|
.I libkeyutils
|
|
|
|
via the function
|
|
|
|
.BR keyctl_get_persistent (3).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" commit ddbb41148724367394d0880c516bfaeed127b52e
|
2016-10-17 15:15:34 +00:00
|
|
|
Compute a Diffie-Hellman shared secret or public key.
|
2016-10-29 16:55:20 +00:00
|
|
|
.\" FIXME What is the use case for KEYCTL_DH_COMPUTE?
|
2016-10-17 15:15:34 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-17 15:15:34 +00:00
|
|
|
argument is a pointer to a set of parameters containing
|
2016-11-03 13:32:51 +00:00
|
|
|
serial numbers for three
|
|
|
|
.IR """user"""
|
|
|
|
keys used in the Diffie-Hellman calculation,
|
2016-10-17 15:15:34 +00:00
|
|
|
packaged in a structure of the following form:
|
2016-09-26 02:24:48 +00:00
|
|
|
|
|
|
|
.nf
|
|
|
|
.in +4n
|
|
|
|
struct keyctl_dh_params {
|
2016-10-17 15:15:34 +00:00
|
|
|
int32_t private; /* The local private key */
|
|
|
|
int32_t prime; /* The prime, known to both parties */
|
|
|
|
int32_t base; /* The base integer: either a shared
|
|
|
|
generator or the remote public key */
|
2016-09-26 02:24:48 +00:00
|
|
|
};
|
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
|
2016-11-03 13:32:51 +00:00
|
|
|
Each of the three keys specified in this structure must grant the caller
|
|
|
|
.I read
|
|
|
|
permission.
|
|
|
|
The payloads of these keys are used to calculate the Diffie-Hellman
|
|
|
|
result as:
|
2016-10-17 15:15:34 +00:00
|
|
|
|
|
|
|
base ^ private mod prime
|
|
|
|
|
|
|
|
If the base is the shared generator, the result is the local public key.
|
|
|
|
If the base is the remote public key, the result is the shared secret.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The
|
|
|
|
.I arg3
|
2016-10-19 08:44:28 +00:00
|
|
|
argument (cast to
|
|
|
|
.IR "char\ *" )
|
2016-10-17 15:15:34 +00:00
|
|
|
points to a buffer where the result of the calculation is placed.
|
|
|
|
The size of that buffer is specified in
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
2016-10-17 15:15:34 +00:00
|
|
|
(cast to
|
2016-10-19 08:44:28 +00:00
|
|
|
.IR size_t ).
|
2016-10-17 15:15:34 +00:00
|
|
|
|
|
|
|
The buffer must be large enough to accommodate the output data,
|
2016-10-17 13:43:16 +00:00
|
|
|
otherwise an error is returned.
|
2016-10-17 15:15:34 +00:00
|
|
|
If
|
|
|
|
.I arg4
|
|
|
|
is specified zero,
|
2016-11-03 13:32:51 +00:00
|
|
|
in which case the buffer is not used and
|
2016-10-17 15:15:34 +00:00
|
|
|
the operation returns the minimum required buffer size
|
|
|
|
(i.e., the length of the prime).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
2016-10-17 13:43:16 +00:00
|
|
|
argument is reserved and must be 0.
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH RETURN VALUE
|
2016-09-26 02:24:48 +00:00
|
|
|
For a successful call, the return value depends on the operation:
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_GET_KEYRING_ID
|
|
|
|
The ID of the requested keyring.
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_JOIN_SESSION_KEYRING
|
|
|
|
The ID of the joined session keyring.
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_DESCRIBE
|
2016-10-19 10:28:07 +00:00
|
|
|
The size of the description (including the terminating null byte),
|
|
|
|
irrespective of the provided buffer size.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_SEARCH
|
2016-10-17 15:35:13 +00:00
|
|
|
The ID of the key that was found.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_READ
|
2016-10-19 11:57:52 +00:00
|
|
|
The amount of data that is available in the key,
|
|
|
|
irrespective of the provided buffer size.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_SET_REQKEY_KEYRING
|
2016-10-20 10:34:34 +00:00
|
|
|
The ID of the previous default keyring
|
|
|
|
to which implicitly requested keys were linked
|
|
|
|
(one of
|
|
|
|
.BR KEY_REQKEY_DEFL_USER_* ).
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_ASSUME_AUTHORITY
|
2016-10-20 11:23:15 +00:00
|
|
|
Either 0, if the ID given was 0,
|
|
|
|
or the ID of the authorization key matching the specified key,
|
|
|
|
if a non-zero key ID was provided.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_GET_SECURITY
|
2016-10-20 12:13:41 +00:00
|
|
|
The size of the LSM security label string
|
|
|
|
(including the terminating null byte),
|
2016-09-26 02:24:48 +00:00
|
|
|
irrespective of the provided buffer size.
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_GET_PERSISTENT
|
2016-10-17 15:35:13 +00:00
|
|
|
The ID of the persistent keyring.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_DH_COMPUTE
|
2016-10-17 15:15:34 +00:00
|
|
|
The number of bytes copied to the buffer, or, if
|
|
|
|
.I arg4
|
|
|
|
is 0, the required buffer size.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
All other commands
|
|
|
|
Zero.
|
|
|
|
.PP
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately to indicate the error.
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B EACCES
|
2016-10-17 13:43:16 +00:00
|
|
|
The requested operation wasn't permitted.
|
2010-11-01 06:18:03 +00:00
|
|
|
.TP
|
2016-10-19 11:07:25 +00:00
|
|
|
.B EDEADLK
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-10-19 11:07:25 +00:00
|
|
|
is
|
|
|
|
.BR KEYCTL_LINK
|
|
|
|
and the requested link would result in a cycle.
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B EDQUOT
|
|
|
|
The key quota for the caller's user would be exceeded by creating a key or
|
|
|
|
linking it to the keyring.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 09:37:45 +00:00
|
|
|
.B EINVAL
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-10-19 09:37:45 +00:00
|
|
|
was
|
|
|
|
.B KEYCTL_SETPERM
|
|
|
|
and an invalid permission bit was specified in
|
|
|
|
.IR arg3 .
|
|
|
|
.TP
|
2016-10-24 10:57:50 +00:00
|
|
|
.B EINVAL
|
|
|
|
.I operation
|
2016-10-27 11:56:23 +00:00
|
|
|
was
|
2016-10-27 12:00:42 +00:00
|
|
|
.BR KEYCTL_SEARCH
|
|
|
|
and the size of the description in
|
|
|
|
.IR arg4
|
|
|
|
(including the terminating null byte) exceeded 4096 bytes.
|
|
|
|
size of the string (including the terminating null byte) specified in
|
|
|
|
.I arg3
|
|
|
|
(the key type)
|
|
|
|
or
|
|
|
|
.I arg4
|
|
|
|
(the key description)
|
|
|
|
exceeded the limit (32 bytes and 4096 bytes respectively).
|
|
|
|
.B EINVAL
|
|
|
|
.I operation
|
|
|
|
was
|
2016-10-24 10:57:50 +00:00
|
|
|
.B KEYCTL_DH_COMPUTE
|
|
|
|
and the buffer size provided is not enough to hold the result.
|
|
|
|
Provide 0 as a buffer size in order to obtain the minimum buffer size.
|
|
|
|
.TP
|
2010-02-25 07:29:42 +00:00
|
|
|
.B EKEYEXPIRED
|
|
|
|
An expired key was found or specified.
|
|
|
|
.TP
|
|
|
|
.B EKEYREJECTED
|
|
|
|
A rejected key was found or specified.
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B EKEYREVOKED
|
|
|
|
A revoked key was found or specified.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2016-10-19 11:07:25 +00:00
|
|
|
.B ELOOP
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-10-19 11:07:25 +00:00
|
|
|
is
|
|
|
|
.BR KEYCTL_LINK
|
|
|
|
and the requested link would cause the maximum nesting depth
|
|
|
|
for keyrings to be exceeded.
|
|
|
|
.TP
|
2016-11-02 22:39:37 +00:00
|
|
|
.BR ENFILE " (Linux kernels before 3.13)"
|
2016-10-24 10:57:50 +00:00
|
|
|
.\" FIXME Does this error really occur? I could not find where
|
2016-10-29 09:42:31 +00:00
|
|
|
.\" in the kernel source it is generated, but have not tested
|
|
|
|
.\" this case from a user-space program
|
2016-10-24 10:57:50 +00:00
|
|
|
.IR operation
|
|
|
|
is
|
|
|
|
.BR KEYCTL_LINK
|
|
|
|
and the keyring is full.
|
2016-11-02 22:39:37 +00:00
|
|
|
(Before Linux 3.13,
|
|
|
|
.\" commit b2a4df200d570b2c33a57e1ebfa5896e4bc81b69
|
|
|
|
the available space for storing keyring links was limited to
|
|
|
|
a single page of memory; since Linux 3.13, there is no fixed limit.)
|
2016-10-24 10:57:50 +00:00
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
.I operation
|
|
|
|
is
|
|
|
|
.B KEYCTL_UNLINK
|
|
|
|
and the key to be unlinked isn't linked to the keyring.
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B ENOKEY
|
|
|
|
No matching key was found or an invalid key was specified.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-10-18 14:43:27 +00:00
|
|
|
.B ENOKEY
|
|
|
|
The value
|
|
|
|
.B KEYCTL_GET_KEYRING_ID
|
|
|
|
was specified in
|
2016-10-20 06:37:52 +00:00
|
|
|
.IR operation ,
|
2016-10-18 14:43:27 +00:00
|
|
|
the key specified in
|
|
|
|
.I arg2
|
|
|
|
did not exist, and
|
|
|
|
.I arg3
|
|
|
|
was zero (meaning don't create the key if it didn't exist).
|
|
|
|
.TP
|
2016-09-26 02:24:48 +00:00
|
|
|
.B ENOTDIR
|
2016-10-19 10:37:39 +00:00
|
|
|
A key of keyring type was expected but the ID of a key with
|
|
|
|
a different type was provided.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-10-24 10:57:50 +00:00
|
|
|
.B EOPNOTSUPP
|
2016-10-20 06:37:52 +00:00
|
|
|
.I operation
|
2016-09-26 02:24:48 +00:00
|
|
|
is
|
2016-10-24 14:25:22 +00:00
|
|
|
.B KEYCTL_READ
|
|
|
|
and the key type does not support reading
|
|
|
|
(e.g., the type is
|
|
|
|
.IR """login""" ).
|
|
|
|
.TP
|
|
|
|
.B EOPNOTSUPP
|
|
|
|
.I operation
|
|
|
|
is
|
2016-10-24 10:57:50 +00:00
|
|
|
.B KEYCTL_UPDATE
|
|
|
|
and the key type does not support updating.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
2016-10-20 12:36:37 +00:00
|
|
|
.B EPERM
|
|
|
|
.I operation
|
|
|
|
was
|
2016-11-02 11:12:57 +00:00
|
|
|
.BR KEYCTL_GET_PERSISTENT ,
|
|
|
|
.I arg2
|
|
|
|
specified a UID other than the calling thread's real or effective UID,
|
|
|
|
and the caller did not have the
|
|
|
|
.B CAP_SETUID
|
|
|
|
capability.
|
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
.I operation
|
|
|
|
was
|
2016-10-20 12:36:37 +00:00
|
|
|
.BR KEYCTL_SESSION_TO_PARENT
|
|
|
|
and either:
|
|
|
|
all of the UIDs (GIDs) of the parent process do not match
|
|
|
|
the effective UID (GID) of the calling process;
|
|
|
|
the UID of the parent's existing session keyring or
|
|
|
|
the UID of the caller's session keyring did not match
|
|
|
|
the effective UID of the caller;
|
|
|
|
the parent process is not single-thread;
|
|
|
|
or the parent process is
|
|
|
|
.BR init (1)
|
|
|
|
or a kernel thread.
|
2016-10-19 08:30:07 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
This system call first appeared in Linux 2.6.11.
|
|
|
|
.SH CONFORMING TO
|
|
|
|
This system call is a nonstandard Linux extension.
|
2016-10-17 13:43:16 +00:00
|
|
|
.SH NOTES
|
2016-10-21 07:42:13 +00:00
|
|
|
No wrapper for this system call is provided in glibc.
|
|
|
|
A wrapper is provided in the
|
|
|
|
.IR libkeyutils
|
|
|
|
package.
|
|
|
|
When employing the wrapper in that library, link with
|
|
|
|
.IR \-lkeyutils .
|
|
|
|
However, rather than using this system call directly,
|
|
|
|
you probably want to use the various library functions
|
|
|
|
mentioned in the descriptions of individual operations above.
|
2010-02-25 07:29:42 +00:00
|
|
|
.SH SEE ALSO
|
2012-09-25 04:05:33 +00:00
|
|
|
.ad l
|
|
|
|
.nh
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl (1),
|
|
|
|
.BR add_key (2),
|
|
|
|
.BR request_key (2),
|
2016-10-21 08:09:32 +00:00
|
|
|
.\" .BR find_key_by_type_and_name (3)
|
|
|
|
.\" There is a man page, but this function seems not to exist
|
|
|
|
.BR keyctl (3),
|
|
|
|
.BR keyctl_assume_authority (3),
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl_chown (3),
|
|
|
|
.BR keyctl_clear (3),
|
2012-09-25 04:00:07 +00:00
|
|
|
.BR keyctl_describe (3),
|
|
|
|
.BR keyctl_describe_alloc (3),
|
|
|
|
.BR keyctl_get_keyring_ID (3),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR keyctl_get_persistent (3),
|
|
|
|
.BR keyctl_get_security (3),
|
|
|
|
.BR keyctl_get_security_alloc (3),
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl_instantiate (3),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR keyctl_instantiate_iov (3),
|
|
|
|
.BR keyctl_invalidate (3),
|
2012-09-25 04:00:07 +00:00
|
|
|
.BR keyctl_join_session_keyring (3),
|
|
|
|
.BR keyctl_link (3),
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl_negate (3),
|
2016-08-07 18:20:26 +00:00
|
|
|
.BR keyctl_read (3),
|
|
|
|
.BR keyctl_read_alloc (3),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR keyctl_reject (3),
|
2012-09-25 04:00:07 +00:00
|
|
|
.BR keyctl_revoke (3),
|
|
|
|
.BR keyctl_search (3),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR keyctl_session_to_parent (3),
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl_set_reqkey_keyring (3),
|
|
|
|
.BR keyctl_set_timeout (3),
|
2016-08-07 18:20:26 +00:00
|
|
|
.BR keyctl_setperm (3),
|
2012-09-25 04:00:07 +00:00
|
|
|
.BR keyctl_unlink (3),
|
|
|
|
.BR keyctl_update (3),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR recursive_key_scan (3),
|
|
|
|
.BR recursive_session_key_scan (3),
|
2015-04-22 12:04:54 +00:00
|
|
|
.BR keyrings (7),
|
2016-10-21 08:09:32 +00:00
|
|
|
.BR keyutils (7),
|
2016-11-02 02:59:30 +00:00
|
|
|
.BR persistent\-keyring (7),
|
|
|
|
.BR process\-keyring (7),
|
|
|
|
.BR session\-keyring (7),
|
|
|
|
.BR thread\-keyring (7),
|
|
|
|
.BR user\-keyring (7),
|
|
|
|
.BR user\-session\-keyring (7),
|
|
|
|
.BR request\-key (8)
|
2014-01-22 09:55:00 +00:00
|
|
|
|
2016-10-20 06:53:19 +00:00
|
|
|
The kernel source files
|
|
|
|
.IR Documentation/security/keys.txt
|
|
|
|
and
|
2016-11-02 02:59:30 +00:00
|
|
|
.IR Documentation/security/keys\-request\-key.txt .
|