2010-02-25 07:29:02 +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:02 +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:02 +00:00
|
|
|
.\"
|
memusage.1, memusagestat.1, pldd.1, accept.2, adjtimex.2, arch_prctl.2, bdflush.2, bpf.2, close.2, epoll_ctl.2, epoll_wait.2, execve.2, execveat.2, fanotify_init.2, fanotify_mark.2, fcntl.2, fsync.2, get_kernel_syms.2, getdomainname.2, getgroups.2, gethostname.2, getrandom.2, getrlimit.2, getrusage.2, getsid.2, getunwind.2, io_getevents.2, ioctl_fat.2, kexec_load.2, killpg.2, listxattr.2, lseek.2, madvise.2, memfd_create.2, mknod.2, mlock.2, modify_ldt.2, msgctl.2, msgget.2, msgop.2, readlink.2, readv.2, reboot.2, recvmmsg.2, rename.2, request_key.2, restart_syscall.2, sched_setaffinity.2, sched_setattr.2, sched_setparam.2, seccomp.2, select_tut.2, semctl.2, semget.2, semop.2, set_thread_area.2, seteuid.2, setgid.2, setpgid.2, setresuid.2, setreuid.2, setsid.2, setuid.2, shmctl.2, shmget.2, shmop.2, sigaction.2, sigprocmask.2, stat.2, symlink.2, syscall.2, sysctl.2, unlink.2, bindresvport.3, byteorder.3, dlopen.3, endian.3, error.3, ffs.3, fmemopen.3, getcwd.3, getlogin.3, getnetent.3, getprotoent.3, getservent.3, getumask.3, getutent.3, glob.3, isalpha.3, lio_listio.3, login.3, mbsinit.3, mbstowcs.3, mbtowc.3, mkstemp.3, nextup.3, ntp_gettime.3, posix_fallocate.3, posix_spawn.3, pthread_join.3, pthread_rwlockattr_setkind_np.3, random.3, rcmd.3, realpath.3, resolver.3, setjmp.3, setnetgrent.3, sigvec.3, strerror.3, strverscmp.3, system.3, toupper.3, towlower.3, towupper.3, wcstombs.3, wordexp.3, cciss.4, loop.4, mouse.4, random.4, core.5, group.5, hosts.5, resolv.conf.5, ascii.7, environ.7, epoll.7, glob.7, ip.7, mq_overview.7, packet.7, pipe.7, raw.7, sched.7, signal.7, socket.7, symlink.7, ld.so.8, sln.8: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2016-10-08 10:53:47 +00:00
|
|
|
.TH REQUEST_KEY 2 2016-10-08 Linux "Linux Key Management Calls"
|
2010-02-25 07:29:02 +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
|
|
|
request_key \- request a key from the kernel's key management facility
|
2010-02-25 07:29:02 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
|
.nf
|
|
|
|
|
.B #include <keyutils.h>
|
|
|
|
|
.sp
|
|
|
|
|
.BI "key_serial_t request_key(const char *" type ", const char *" description ,
|
2011-11-07 03:46:44 +00:00
|
|
|
.BI " const char *" callout_info ,
|
|
|
|
|
.BI " key_serial_t " keyring ");"
|
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:30 +00:00
|
|
|
|
|
|
|
|
No glibc wrapper is provided for this system call; see NOTES.
|
2010-02-25 07:29:02 +00:00
|
|
|
.SH DESCRIPTION
|
|
|
|
|
.BR request_key ()
|
2016-10-20 19:41:20 +00:00
|
|
|
attempts to find a key of the given
|
2010-02-25 07:29:02 +00:00
|
|
|
.I type
|
2016-10-20 19:41:20 +00:00
|
|
|
with a description (name) that matches the specified
|
2010-02-25 07:29:02 +00:00
|
|
|
.I description
|
2016-10-20 19:41:20 +00:00
|
|
|
and, if successful, attaches it to the nominated
|
2010-02-25 07:29:02 +00:00
|
|
|
.I keyring
|
2016-10-20 19:41:20 +00:00
|
|
|
and returns its serial number.
|
2010-02-25 07:29:02 +00:00
|
|
|
.P
|
|
|
|
|
.BR request_key ()
|
2016-10-20 19:41:20 +00:00
|
|
|
first recursively searches for a matching key in all of the keyrings
|
|
|
|
|
attached to the calling process.
|
|
|
|
|
The keyrings are searched in the order: thread-specific keyring,
|
|
|
|
|
process-specific keyring, and then session keyring.
|
2010-02-25 07:29:02 +00:00
|
|
|
.P
|
|
|
|
|
If
|
|
|
|
|
.BR request_key ()
|
|
|
|
|
is called from a program invoked by
|
|
|
|
|
.BR request_key ()
|
|
|
|
|
on behalf of some other process to generate a key, then the keyrings of that
|
2016-10-20 19:41:20 +00:00
|
|
|
other process will be searched next,
|
|
|
|
|
using that other process's user ID, group ID,
|
|
|
|
|
supplementary group IDs, and security context to control access.
|
2010-02-25 07:29:02 +00:00
|
|
|
.P
|
|
|
|
|
The keys in each keyring searched are checked for a match before any child
|
2012-05-05 03:10:16 +00:00
|
|
|
keyrings are recursed into.
|
|
|
|
|
Only keys that are
|
2010-02-25 07:29:02 +00:00
|
|
|
.B searchable
|
|
|
|
|
for the caller may be found, and only
|
|
|
|
|
.B searchable
|
|
|
|
|
keyrings may be searched.
|
|
|
|
|
.P
|
2014-01-10 17:25:02 +00:00
|
|
|
If the key is not found, then, if
|
2010-02-25 07:29:02 +00:00
|
|
|
.I callout_info
|
2016-10-20 19:41:20 +00:00
|
|
|
is not NULL, this function will attempt to look further afield.
|
2012-05-05 03:10:16 +00:00
|
|
|
In such a case, the
|
2010-02-25 07:29:02 +00:00
|
|
|
.I callout_info
|
eventfd.2, futex.2, mmap2.2, open.2, pciconfig_read.2, ptrace.2, reboot.2, request_key.2, sched_rr_get_interval.2, splice.2, stat.2, sync_file_range.2, syscalls.2, timer_create.2, vm86.2, pthread_attr_setscope.3, core.5, proc.5, aio.7, futex.7, netlink.7, time.7: Global fix: "userspace" ==> "user space" or "user-space"
Existing pages variously use "userspace or "user space".
But, "userspace" is not quite an English word.
So change "userspace" to "user space" or, when used
attributively, "user-space".
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2012-10-21 06:04:42 +00:00
|
|
|
is passed to a user-space service such as
|
2016-10-20 19:41:20 +00:00
|
|
|
.I /sbin/request\-key
|
2010-02-25 07:29:02 +00:00
|
|
|
to generate the key.
|
|
|
|
|
.P
|
|
|
|
|
If that is unsuccessful also, then an error will be returned, and a temporary
|
|
|
|
|
negative key will be installed in the nominated
|
|
|
|
|
.IR keyring .
|
|
|
|
|
This will expire after a few seconds, but will cause subsequent
|
|
|
|
|
calls to
|
|
|
|
|
.BR request_key ()
|
|
|
|
|
to fail until it does.
|
|
|
|
|
.P
|
|
|
|
|
The
|
|
|
|
|
.I keyring
|
|
|
|
|
serial number may be that of a valid keyring to which the caller has write
|
2016-10-20 19:41:20 +00:00
|
|
|
permission, or it may be one of the following special keyring IDs:
|
2010-02-25 07:29:02 +00:00
|
|
|
.TP
|
|
|
|
|
.B KEY_SPEC_THREAD_KEYRING
|
|
|
|
|
This specifies the caller's thread-specific keyring.
|
|
|
|
|
.TP
|
|
|
|
|
.B KEY_SPEC_PROCESS_KEYRING
|
|
|
|
|
This specifies the caller's process-specific keyring.
|
|
|
|
|
.TP
|
|
|
|
|
.B KEY_SPEC_SESSION_KEYRING
|
|
|
|
|
This specifies the caller's session-specific keyring.
|
|
|
|
|
.TP
|
|
|
|
|
.B KEY_SPEC_USER_KEYRING
|
|
|
|
|
This specifies the caller's UID-specific keyring.
|
|
|
|
|
.TP
|
|
|
|
|
.B KEY_SPEC_USER_SESSION_KEYRING
|
|
|
|
|
This specifies the caller's UID-session keyring.
|
|
|
|
|
.P
|
|
|
|
|
If a key is created, no matter whether it's a valid key or a negative key, it
|
|
|
|
|
will displace any other key of the same type and description from the
|
|
|
|
|
destination
|
|
|
|
|
.IR keyring .
|
|
|
|
|
.SH RETURN VALUE
|
2016-10-20 19:41:20 +00:00
|
|
|
On success,
|
2010-02-25 07:29:02 +00:00
|
|
|
.BR request_key ()
|
|
|
|
|
returns the serial number of the key it found.
|
2016-10-20 19:41:20 +00:00
|
|
|
On error, \-1 is returned and
|
|
|
|
|
.I errno
|
|
|
|
|
is set to indicate the cause of the error.
|
2010-02-25 07:29:02 +00:00
|
|
|
.SH ERRORS
|
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B EACCES
|
|
|
|
|
The keyring wasn't available for modification by the user.
|
|
|
|
|
.TP
|
|
|
|
|
.B EDQUOT
|
|
|
|
|
The key quota for this user would be exceeded by creating this key or linking
|
|
|
|
|
it to the keyring.
|
2010-02-25 07:29:02 +00:00
|
|
|
.TP
|
2016-08-07 17:10:00 +00:00
|
|
|
.B EINTR
|
|
|
|
|
The request was interrupted by a signal; see
|
|
|
|
|
.BR signal (7).
|
|
|
|
|
.TP
|
2010-02-25 07:29:02 +00:00
|
|
|
.B EKEYEXPIRED
|
|
|
|
|
An expired key was found, but no replacement could be obtained.
|
|
|
|
|
.TP
|
|
|
|
|
.B EKEYREJECTED
|
|
|
|
|
The attempt to generate a new key was rejected.
|
|
|
|
|
.TP
|
2010-11-01 06:18:03 +00:00
|
|
|
.B EKEYREVOKED
|
|
|
|
|
A revoked key was found, but no replacement could be obtained.
|
|
|
|
|
.TP
|
|
|
|
|
.B ENOKEY
|
|
|
|
|
No matching key was found.
|
2016-08-07 17:10:00 +00:00
|
|
|
.TP
|
|
|
|
|
.B ENOMEM
|
|
|
|
|
Insufficient memory to create a key.
|
2016-10-19 08:30:35 +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-19 08:29:50 +00:00
|
|
|
.SH NOTES
|
2016-10-21 07:42:30 +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 .
|
2010-02-25 07:29:02 +00:00
|
|
|
.SH SEE ALSO
|
|
|
|
|
.BR keyctl (1),
|
|
|
|
|
.BR add_key (2),
|
|
|
|
|
.BR keyctl (2),
|
2015-04-22 12:06:47 +00:00
|
|
|
.BR keyctl (3),
|
2015-04-22 12:04:54 +00:00
|
|
|
.BR keyrings (7),
|
2010-02-25 07:29:02 +00:00
|
|
|
.BR request-key (8)
|
2016-10-20 06:46:46 +00:00
|
|
|
|
|
|
|
|
The kernel source files
|
|
|
|
|
.IR Documentation/security/keys.txt
|
|
|
|
|
and
|
|
|
|
|
.IR Documentation/security/keys-request-key.txt .
|