2010-02-25 07:29:42 +00:00
|
|
|
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
|
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
|
|
|
.\"
|
2013-03-10 09:29:47 +00:00
|
|
|
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
|
2010-02-25 07:29:42 +00:00
|
|
|
.\" This program is free software; you can redistribute it and/or
|
|
|
|
.\" modify it under the terms of the GNU General Public License
|
|
|
|
.\" as published by the Free Software Foundation; either version
|
|
|
|
.\" 2 of the License, or (at your option) any later version.
|
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
|
|
|
|
.B #include <keyutils.h>
|
|
|
|
.sp
|
2016-09-26 02:24:48 +00:00
|
|
|
.BI "long keyctl(int " cmd ", ...)"
|
|
|
|
.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-17 13:35:25 +00:00
|
|
|
.BI "long syscall(__NR_keyctl, int " option ", __kernel_ulong_t " arg2 ,
|
|
|
|
.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
|
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
|
|
|
|
.I option
|
|
|
|
argument.
|
|
|
|
Each of these operations is wrapped by
|
|
|
|
.B libkeyutils
|
|
|
|
into individual functions (listed under SEE ALSO)
|
|
|
|
to permit the compiler to check types.
|
|
|
|
|
|
|
|
The permitted values for
|
2016-09-26 02:24:48 +00:00
|
|
|
.I option
|
2016-10-17 13:43:16 +00:00
|
|
|
are:
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_GET_KEYRING_ID
|
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-18 14:43:27 +00:00
|
|
|
(which is cast as
|
|
|
|
.IR key_serial_t )
|
|
|
|
and (if it is found) the ID of corresponding real key is returned
|
|
|
|
|
|
|
|
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-18 14:43:27 +00:00
|
|
|
argument (cast as an
|
|
|
|
.IR int )
|
|
|
|
contains a non-zero value; otherwise the operation fails with the error
|
|
|
|
.BR ENOKEY .
|
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
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_JOIN_SESSION_KEYRING
|
2016-10-17 13:43:16 +00:00
|
|
|
Create a new anonymous session keyring (in case
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
is
|
|
|
|
.BR NULL )
|
2016-10-17 13:43:16 +00:00
|
|
|
or join an existing named session keyring
|
2016-09-26 02:24:48 +00:00
|
|
|
.RI ( arg2
|
2016-10-17 13:43:16 +00:00
|
|
|
should be a pointer to a string containing session name in this case).
|
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-17 13:43:16 +00:00
|
|
|
permission on the keyring name which is provided in order
|
2016-10-17 13:42:58 +00:00
|
|
|
to successfully join.
|
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.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_UPDATE
|
2016-10-17 13:43:16 +00:00
|
|
|
Update a key's data payload.
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.IR key_serial_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
should contain the key ID.
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument is interpreted as a pointer to the new payload and
|
|
|
|
.I arg4
|
|
|
|
(converted to
|
|
|
|
.IR size_t )
|
2016-10-17 13:43:16 +00:00
|
|
|
should contain the payload size in bytes.
|
|
|
|
|
|
|
|
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.
|
|
|
|
A negative key can be positively instantiated with this call.
|
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_REVOKE
|
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
|
|
|
|
(converted to
|
|
|
|
.IR key_serial_t ).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR write " or " setattr
|
2016-10-17 13:43:16 +00:00
|
|
|
permission on they key.
|
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_CHOWN
|
2016-10-17 13:43:16 +00:00
|
|
|
Set the ownership of a key.
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.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
|
|
|
|
argument (converted to
|
|
|
|
.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
|
|
|
|
argument (converted to
|
|
|
|
.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-09-26 02:24:48 +00:00
|
|
|
The key must grant the caller
|
|
|
|
.I setattr
|
2016-10-17 13:42:58 +00:00
|
|
|
permission.
|
|
|
|
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-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
|
|
|
|
to the new user should the attribute 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.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_SETPERM
|
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
|
|
|
|
argument (converted to
|
|
|
|
.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
|
|
|
|
argument (converted to
|
|
|
|
.IR key_perms_t ).
|
|
|
|
The key must grant
|
|
|
|
.I setattr
|
2016-10-17 13:42:58 +00:00
|
|
|
permission to the caller.
|
|
|
|
If the caller doesn't have
|
2016-10-17 13:43:16 +00:00
|
|
|
.B CAP_SYS_ADMIN
|
|
|
|
capability, it can change permissions only for the keys it owns.
|
|
|
|
Permissions contains a mask of available operations for possessor
|
2016-10-17 13:42:58 +00:00
|
|
|
(since Linux 2.6.14), user, group, other.
|
2016-10-17 13:43:16 +00:00
|
|
|
Each 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
|
|
|
|
.IP \(bu 3
|
|
|
|
.BR View .
|
2016-10-17 13:42:58 +00:00
|
|
|
Allows reading attributes of a key.
|
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_DESCRIBE .
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP \(bu
|
|
|
|
.BR Read .
|
2016-10-17 13:43:16 +00:00
|
|
|
Allows reading a key's payload.
|
2016-10-17 13:42:58 +00:00
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_READ .
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP \(bu
|
|
|
|
.BR Write .
|
2016-10-17 13:43:16 +00:00
|
|
|
Allows update or instantiation of a key's payload.
|
|
|
|
For a keyring, it enables addition and removal of keys to a keyring.
|
2016-10-17 13:42:58 +00:00
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_UPDATE ,
|
|
|
|
.BR KEYCTL_REVOKE ,
|
|
|
|
.BR KEYCTL_CLEAR ,
|
|
|
|
.BR KEYCTL_LINK ,
|
|
|
|
and
|
|
|
|
.BR KEYCTL_UNLINK .
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP \(bu
|
|
|
|
.BR Search .
|
2016-10-17 13:42:58 +00:00
|
|
|
This permits keyrings to be searched and keys to be found.
|
|
|
|
Searches can only recurse into nested keyrings
|
|
|
|
that have search permission set.
|
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_GET_KEYRING_ID ,
|
|
|
|
.BR KEYCTL_JOIN_SESSION_KEYRING ,
|
|
|
|
.BR KEYCTL_SEARCH ,
|
|
|
|
and
|
|
|
|
.BR KEYCTL_INVALIDATE .
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP \(bu
|
|
|
|
.BR Link .
|
2016-10-17 13:42:58 +00:00
|
|
|
This permits a key or keyring to be linked to.
|
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_LINK
|
|
|
|
and
|
|
|
|
.BR KEYCTL_SESSION_TO_PARENT .
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP \(bu
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR "Set attribute" " (since Linux 2.6.15)."
|
|
|
|
This permits a key's UID, GID, and permissions mask to be changed.
|
2016-10-17 13:42:58 +00:00
|
|
|
Needed for
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEYCTL_REVOKE ,
|
|
|
|
.BR KEYCTL_CHOWN ,
|
|
|
|
and
|
|
|
|
.BR KEYCTL_SETPERM .
|
2016-09-26 02:24:48 +00:00
|
|
|
.RE
|
|
|
|
.IP
|
|
|
|
The
|
|
|
|
.IR arg4 " and " arg5
|
|
|
|
arguments are ignored.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_DESCRIBE
|
2016-10-17 13:42:58 +00:00
|
|
|
Describe a key.
|
2016-10-17 13:43:16 +00:00
|
|
|
The ID of the key to be described should be provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
2016-10-17 13:43:16 +00:00
|
|
|
.IR key_serial_t ).
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
2016-10-17 13:43:16 +00:00
|
|
|
argument should point to the destination buffer (of type
|
2016-10-19 09:40:31 +00:00
|
|
|
.IR "char\ *" ),
|
2016-09-26 02:24:48 +00:00
|
|
|
and the
|
|
|
|
.I arg4
|
|
|
|
argument should contain size of the buffer (of kernel's
|
|
|
|
.I size_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
|
|
|
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-17 13:43:16 +00:00
|
|
|
Writing to the buffer is attempted only when the buffer is non-NULL and
|
2016-09-26 02:24:48 +00:00
|
|
|
has enough space to accept the description.
|
|
|
|
'\" Function commentary says it copies up to buflen bytes, bu see the
|
|
|
|
'\" (buffer && buflen >= ret) condition in keyctl_describe_key() in
|
|
|
|
'\" security/keyctl.c
|
2016-10-17 13:43:16 +00:00
|
|
|
The description itself is provided in the format:
|
2016-09-26 02:24:48 +00:00
|
|
|
.RS
|
|
|
|
.IP
|
|
|
|
.IR type ; uid ; gid ; perm ; description "<NUL>"
|
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_CLEAR
|
2016-10-17 13:43:16 +00:00
|
|
|
Clear the contents of the keyring with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.IR key_serial_t ).
|
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:42:58 +00:00
|
|
|
permission.
|
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.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_LINK
|
2016-09-26 02:24:48 +00:00
|
|
|
Link a key (provided in the
|
|
|
|
.I arg2
|
|
|
|
argument converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type) to a keyring (provided in the
|
|
|
|
.I arg3
|
|
|
|
argument converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type) of there is no matching key in the keyring, or replace the link
|
2016-10-17 13:42:58 +00:00
|
|
|
to the matching key with a link to the new key.
|
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-17 13:42:58 +00:00
|
|
|
permission on the keyring to which key being added to.
|
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.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_UNLINK
|
2016-09-26 02:24:48 +00:00
|
|
|
Unlink a key (provided in the
|
|
|
|
.I arg2
|
|
|
|
argument converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type) from a keyring (provided in the
|
|
|
|
.I arg3
|
|
|
|
argument converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
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-17 13:42:58 +00:00
|
|
|
If the last link
|
2016-10-17 13:43:16 +00:00
|
|
|
to a key is removed, then that key will be scheduled for destruction.
|
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_SEARCH
|
2016-10-17 13:43:16 +00:00
|
|
|
Search for a key in a keyring with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument should be a
|
2016-10-19 09:40:31 +00:00
|
|
|
.IR "char\ *"
|
2016-10-17 13:43:16 +00:00
|
|
|
pointing to the name of the type of the key being searched for
|
|
|
|
(NUL-terminated character string up to 32 bytes in size), and the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
|
|
|
argument should be a
|
2016-10-19 09:40:31 +00:00
|
|
|
.IR "char\ *"
|
2016-10-17 13:43:16 +00:00
|
|
|
pointing to a NUL-terminated character string (up to 4096 bytes in size)
|
|
|
|
with the description of the key being searched for.
|
2016-10-17 13:42:58 +00:00
|
|
|
The search is performed recursively
|
2016-10-17 13:43:16 +00:00
|
|
|
starting from the keyring with the ID provided in
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR arg2 .
|
|
|
|
Only keyrings that grant the caller
|
|
|
|
.I search
|
|
|
|
permission will be searched (this includes the starting keyring).
|
|
|
|
Only keys with
|
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission can be found.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
If the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:43:16 +00:00
|
|
|
type) contains a non-zero value, it is interpreted as a keyring ID to which
|
2016-09-26 02:24:48 +00:00
|
|
|
the found key should be linked.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_READ
|
2016-10-17 13:43:16 +00:00
|
|
|
Read the payload of the key whose ID is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:43:16 +00:00
|
|
|
type).
|
|
|
|
The payload is placed in the buffer pointed by the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I char *
|
2016-10-17 13:43:16 +00:00
|
|
|
type);
|
|
|
|
the size of that buffer must be provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
|
|
|
argument (converted to kernel's
|
|
|
|
.I size_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
|
|
|
The key must either grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I read
|
|
|
|
permission, or it must grant the caller
|
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission when searched for from the process keyrings.
|
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.
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_INSTANTIATE
|
2016-10-17 13:43:16 +00:00
|
|
|
Instantiate a partially constructed key whose ID is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type) with a payload pointed by the
|
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I char *
|
|
|
|
type) of size provided in the
|
|
|
|
.I arg4
|
|
|
|
argument (converted to kernel's
|
|
|
|
.I size_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
The instantiated key will be linked to the keyring ID which is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
|
|
|
The caller must have the appropriate instantiation permit set (auth key).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2010-02-25 07:29:42 +00:00
|
|
|
.TP
|
2012-03-20 17:24:41 +00:00
|
|
|
.B KEYCTL_NEGATE
|
2016-10-17 13:43:16 +00:00
|
|
|
Negatively instantiate a partially constructed key with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:43:16 +00:00
|
|
|
type), setting the timeout (in seconds) to the value provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I unsigned int
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
The instantiated key will be linked to the keyring ID which is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
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-17 13:42:58 +00:00
|
|
|
command).
|
2016-10-17 13:43:16 +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)
|
|
|
|
calls by causing them to fail with the error
|
|
|
|
.B ENOKEY
|
2016-10-17 13:42:58 +00:00
|
|
|
until the negative key expires.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
|
|
|
This is equivalent to the call
|
|
|
|
|
|
|
|
keyctl(KEYCTL_REJECT, arg2, arg3, ENOKEY, arg4);
|
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The
|
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
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-17 13:43:16 +00:00
|
|
|
Read or set the default keyring in which
|
|
|
|
.BR request_key (2)
|
2016-10-17 13:42:58 +00:00
|
|
|
will cache keys.
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I int
|
|
|
|
type) should contain one of the following values, defined in
|
|
|
|
.IR <linux/keyring.h> :
|
2016-10-17 14:17:48 +00:00
|
|
|
.RS
|
|
|
|
.TP 33
|
|
|
|
.BR KEY_REQKEY_DEFL_NO_CHANGE
|
|
|
|
No change.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_DEFAULT
|
|
|
|
Default keyring.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_THREAD_KEYRING
|
|
|
|
Thread-specific keyring.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_PROCESS_KEYRING
|
|
|
|
Process-specific keyring.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_SESSION_KEYRING
|
|
|
|
Session-specific keyring.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_USER_KEYRING
|
|
|
|
UID-specific keyring.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_USER_SESSION_KEYRING 5
|
|
|
|
Session keyring of UID.
|
|
|
|
.TP
|
|
|
|
.BR KEY_REQKEY_DEFL_REQUESTOR_KEYRING " (since Linux 2.6.29)"
|
2016-09-26 02:24:48 +00:00
|
|
|
'\" 8bbf4976b59fc9fc2861e79cab7beb3f6d647640
|
2016-10-17 14:17:48 +00:00
|
|
|
Requestor keyring.
|
|
|
|
.RE
|
|
|
|
.IP
|
2016-10-17 13:43:16 +00:00
|
|
|
All other values are invalid (including the as-yet-unsupported
|
|
|
|
.BR KEY_REQKEY_DEFL_GROUP_KEYRING ).
|
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg3 ,
|
|
|
|
.IR arg4 ,
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
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-17 13:42:58 +00:00
|
|
|
Set timeout on a key.
|
|
|
|
ID of a key provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type), timeout value (in seconds from current time) provided in the
|
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I unsigned int
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
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-17 13:43:16 +00:00
|
|
|
permission or hold an instantiation authorization token for the key.
|
|
|
|
|
|
|
|
A timeout value of 0 clears the timeout.
|
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-17 13:43:16 +00:00
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
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-17 13:42:58 +00:00
|
|
|
Assume (or clear) the authority for the key instantiation.
|
2016-10-17 13:43:16 +00:00
|
|
|
The ID of the authorization key provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The caller must have the instantiation key in their process keyrings
|
2016-09-26 02:24:48 +00:00
|
|
|
with a
|
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission grant available to the caller.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
If the ID given in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
2016-10-17 13:42:58 +00:00
|
|
|
argument is 0, then the setting will be cleared.
|
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.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_GET_SECURITY " (since Linux 2.6.26)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Get the LSM security label of the specified key.
|
2016-10-17 13:42:58 +00:00
|
|
|
The ID of the key should be provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
The buffer where the security label should be stored is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I char *
|
|
|
|
type) with its size provided in the
|
|
|
|
.I arg4
|
|
|
|
argument (converted to kernel's
|
|
|
|
.I size_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
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.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_SESSION_TO_PARENT " (since Linux 2.6.32)"
|
|
|
|
Apply session keyring to parent process.
|
|
|
|
.IP
|
2016-10-17 13:42:58 +00:00
|
|
|
Attempt to install the calling process's session keyring
|
|
|
|
on the process's parent process.
|
|
|
|
The keyring must exist and must grant the caller
|
2016-09-26 02:24:48 +00:00
|
|
|
.I link
|
2016-10-17 13:43:16 +00:00
|
|
|
permission, and the parent process must be single-threaded and have
|
|
|
|
the same effective ownership as this process
|
|
|
|
and must not be be set-user-ID or set-group-ID.
|
2016-09-26 02:24:48 +00:00
|
|
|
.IP
|
|
|
|
The keyring will be emplaced on the parent when it next resumes userspace.
|
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.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_REJECT " (since Linux 2.6.39)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Negatively instantiate a partially constructed key with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
|
|
|
type), setting timeout (in seconds) to the value provided in the
|
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I unsigned int
|
|
|
|
type) and instantiation error to the value provided in the
|
|
|
|
.I arg4
|
|
|
|
argument (converted to
|
|
|
|
.I unsigned int
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
The instantiated key will be linked to the keyring ID which is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
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-17 13:42:58 +00:00
|
|
|
command).
|
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.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_INSTANTIATE_IOV " (since Linux 2.6.39)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Instantiate a key (with the ID specified in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument of type
|
|
|
|
.IR key_serial_t )
|
|
|
|
with the specified (in the
|
|
|
|
.I arg3
|
|
|
|
argument of type
|
2016-10-19 09:40:31 +00:00
|
|
|
.IR "const struct iovec\ *" )
|
2016-09-26 02:24:48 +00:00
|
|
|
multipart payload and link the key into
|
2016-10-17 13:43:16 +00:00
|
|
|
the destination keyring (whose ID is provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
|
|
|
argument of type
|
|
|
|
.IR key_serial_t )
|
2016-10-17 13:42:58 +00:00
|
|
|
if non-zero one is given.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The caller must have the appropriate instantiation
|
2016-10-17 13:43:16 +00:00
|
|
|
permit (authorization key, see
|
|
|
|
.B KEYCTL_ASSUME_AUTHORITY
|
2016-10-17 13:42:58 +00:00
|
|
|
command) set for this to work.
|
|
|
|
No other permissions are required.
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 15:35:13 +00:00
|
|
|
.\" FIXME The following sentence appears not to be true,
|
|
|
|
.\" according to my reading of the source code.
|
2016-10-17 13:42:58 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg5
|
|
|
|
argument is ignored.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_INVALIDATE " (since Linux 3.5)"
|
2016-10-17 13:43:16 +00:00
|
|
|
Invalidate a key with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-10-17 13:42:58 +00:00
|
|
|
The caller must have
|
2016-09-26 02:24:48 +00:00
|
|
|
.I search
|
2016-10-17 13:42:58 +00:00
|
|
|
permission in order to perform invalidation.
|
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 immediately.
|
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.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_GET_PERSISTENT " (since Linux 3.13)"
|
|
|
|
Get the persistent keyring of the user specified in the
|
|
|
|
.I arg2
|
|
|
|
(converted to
|
|
|
|
.I uid_t
|
2016-10-17 13:43:16 +00:00
|
|
|
type) and link it to the keyring with the ID provided in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I key_serial_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
If \-1 is provided as UID, current user's ID is used.
|
|
|
|
|
|
|
|
The arguments
|
|
|
|
.IR arg4
|
|
|
|
and
|
|
|
|
.IR arg5
|
2016-09-26 02:24:48 +00:00
|
|
|
are ignored.
|
|
|
|
.TP
|
|
|
|
.BR KEYCTL_DH_COMPUTE " (since Linux 4.7)"
|
2016-10-17 13:42:58 +00:00
|
|
|
Compute Diffie-Hellman values.
|
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg2
|
|
|
|
argument is a pointer to
|
2016-10-17 13:43:16 +00:00
|
|
|
.I struct keyctl_dh_params
|
2016-09-26 02:24:48 +00:00
|
|
|
which is defined in
|
|
|
|
.I <linux/keyctl.h>
|
|
|
|
as follows:
|
|
|
|
|
|
|
|
.nf
|
|
|
|
.in +4n
|
|
|
|
struct keyctl_dh_params {
|
|
|
|
int32_t private;
|
|
|
|
int32_t prime;
|
|
|
|
int32_t base;
|
|
|
|
};
|
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
|
2016-10-17 13:43:16 +00:00
|
|
|
The
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR private ", " prime " and " base
|
2016-10-17 13:43:16 +00:00
|
|
|
fields are IDs of the keys, payload of which would be used for DH values
|
2016-10-17 13:42:58 +00:00
|
|
|
calculation.
|
2016-10-17 13:43:16 +00:00
|
|
|
The result is calculated as
|
2016-09-26 02:24:48 +00:00
|
|
|
.IR "base^private mod prime" .
|
2016-10-17 13:43:16 +00:00
|
|
|
|
2016-09-26 02:24:48 +00:00
|
|
|
The
|
|
|
|
.I arg3
|
|
|
|
argument (converted to
|
|
|
|
.I char *
|
2016-10-17 13:43:16 +00:00
|
|
|
type) should point to an output buffer whose size is passed in the
|
2016-09-26 02:24:48 +00:00
|
|
|
.I arg4
|
|
|
|
argument (converted to kernel's
|
|
|
|
.I size_t
|
2016-10-17 13:42:58 +00:00
|
|
|
type).
|
2016-10-17 13:43:16 +00:00
|
|
|
The buffer should be big enough in order to accommodate the output data,
|
|
|
|
otherwise an error is returned.
|
|
|
|
A NULL pointer can be provided as buffer in order
|
|
|
|
to obtain the required buffer size.
|
|
|
|
|
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-17 13:43:16 +00:00
|
|
|
The size of description (including the terminating null byte), irrespective
|
2016-09-26 02:24:48 +00:00
|
|
|
of the provided buffer size.
|
|
|
|
.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
|
|
|
|
The amount of data that is available in the key, irrespective of the provided
|
|
|
|
buffer size.
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_SET_REQKEY_KEYRING
|
|
|
|
Old setting (one of
|
2016-10-17 13:43:16 +00:00
|
|
|
.BR KEY_REQKEY_DEFL_USER_* )
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B KEYCTL_ASSUME_AUTHORITY
|
2016-10-17 13:42:58 +00:00
|
|
|
0, if the ID given is 0.
|
2016-10-17 13:43:16 +00:00
|
|
|
ID of the authorization key matching key with the given
|
2016-09-26 02:24:48 +00:00
|
|
|
ID if non-zero key ID provided.
|
|
|
|
.TP
|
|
|
|
.B KEYCTL_GET_SECURITY
|
2016-10-17 13:43:16 +00:00
|
|
|
The amount of information available (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
|
|
|
|
Amount of bytes being copied.
|
|
|
|
.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
|
|
|
|
.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
|
|
|
|
.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
|
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
|
|
|
|
.IR option ,
|
|
|
|
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 ENOTSUPP
|
|
|
|
.I option
|
|
|
|
is
|
|
|
|
.B KEYCTL_UPDATE
|
2016-10-17 13:43:16 +00:00
|
|
|
and the key type does not support updating.
|
2016-09-26 02:24:48 +00:00
|
|
|
.TP
|
|
|
|
.B ENOTDIR
|
|
|
|
Key of keyring type is expected but ID of a key with a different type provided.
|
|
|
|
.TP
|
|
|
|
.B ENFILE
|
|
|
|
Keyring is full.
|
|
|
|
.TP
|
|
|
|
.B ENOENT
|
|
|
|
.I option
|
|
|
|
is
|
|
|
|
.B KEYCTL_UNLINK
|
|
|
|
and the key requested for unlinking isn't linked to the keyring.
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I option
|
|
|
|
is
|
|
|
|
.B KEYCTL_DH_COMPUTE
|
2016-10-17 13:43:16 +00:00
|
|
|
and the buffer size provided is not enough for the result to fit in.
|
2016-10-17 13:42:58 +00:00
|
|
|
Provide 0 as
|
2016-09-26 02:24:48 +00:00
|
|
|
a buffer size in order to obtain minimum buffer size first.
|
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
|
2010-02-25 07:29:42 +00:00
|
|
|
Although this is a Linux system call, it is not present in
|
|
|
|
.I libc
|
|
|
|
but can be found rather in
|
|
|
|
.IR libkeyutils .
|
|
|
|
When linking,
|
2016-10-17 13:43:16 +00:00
|
|
|
.B \-lkeyutils
|
2010-02-25 07:29:42 +00:00
|
|
|
should be specified to the linker.
|
|
|
|
.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),
|
|
|
|
.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),
|
2010-02-25 07:29:42 +00:00
|
|
|
.BR keyctl_instantiate (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),
|
2012-09-25 04:00:07 +00:00
|
|
|
.BR keyctl_revoke (3),
|
|
|
|
.BR keyctl_search (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),
|
2015-04-22 12:04:54 +00:00
|
|
|
.BR keyrings (7),
|
2010-02-25 07:29:42 +00:00
|
|
|
.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
|
|
|
|
.IR Documentation/security/keys-request-key.txt .
|