mirror of https://github.com/mkerrisk/man-pages
163 lines
4.6 KiB
Groff
163 lines
4.6 KiB
Groff
.\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
|
|
.\" Written by David Howells (dhowells@redhat.com)
|
|
.\"
|
|
.\" %%%LICENSE_START(GPLv2+_SW_ONEPARA)
|
|
.\" 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.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.TH REQUEST_KEY 2 2016-10-08 Linux "Linux Key Management Calls"
|
|
.SH NAME
|
|
request_key \- request a key from the kernel's key management facility
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <keyutils.h>
|
|
.sp
|
|
.BI "key_serial_t request_key(const char *" type ", const char *" description ,
|
|
.BI " const char *" callout_info ,
|
|
.BI " key_serial_t " keyring ");"
|
|
.fi
|
|
|
|
No glibc wrapper is provided for this system call; see NOTES.
|
|
.SH DESCRIPTION
|
|
.BR request_key ()
|
|
attempts to find a key of the given
|
|
.I type
|
|
with a description (name) that matches the specified
|
|
.I description
|
|
and, if successful, attaches it to the nominated
|
|
.I keyring
|
|
and returns its serial number.
|
|
.P
|
|
.BR request_key ()
|
|
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.
|
|
.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
|
|
other process will be searched next,
|
|
using that other process's user ID, group ID,
|
|
supplementary group IDs, and security context to control access.
|
|
.P
|
|
The search of the keyring tree is breadth-first:
|
|
the keys in each keyring searched are checked for a match before any child
|
|
keyrings are recursed into.
|
|
Only keys that are
|
|
.B searchable
|
|
for the caller may be found, and only
|
|
.B searchable
|
|
keyrings may be searched.
|
|
.P
|
|
If the key is not found, then, if
|
|
.I callout_info
|
|
is not NULL, this function will attempt to look further afield.
|
|
In such a case, the
|
|
.I callout_info
|
|
is passed to a user-space service such as
|
|
.I /sbin/request\-key
|
|
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
|
|
permission, or it may be one of the following special keyring IDs:
|
|
.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
|
|
On success,
|
|
.BR request_key ()
|
|
returns the serial number of the key it found.
|
|
On error, \-1 is returned and
|
|
.I errno
|
|
is set to indicate the cause of the error.
|
|
.SH ERRORS
|
|
.TP
|
|
.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.
|
|
.TP
|
|
.B EINTR
|
|
The request was interrupted by a signal; see
|
|
.BR signal (7).
|
|
.TP
|
|
.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
|
|
.B EKEYREVOKED
|
|
A revoked key was found, but no replacement could be obtained.
|
|
.TP
|
|
.B ENOKEY
|
|
No matching key was found.
|
|
.TP
|
|
.B ENOMEM
|
|
Insufficient memory to create a key.
|
|
.SH VERSIONS
|
|
This system call first appeared in Linux 2.6.11.
|
|
.SH CONFORMING TO
|
|
This system call is a nonstandard Linux extension.
|
|
.SH NOTES
|
|
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 .
|
|
.SH SEE ALSO
|
|
.BR keyctl (1),
|
|
.BR add_key (2),
|
|
.BR keyctl (2),
|
|
.BR keyctl (3),
|
|
.BR keyrings (7),
|
|
.BR keyutils (7),
|
|
.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)
|
|
|
|
The kernel source files
|
|
.IR Documentation/security/keys.txt
|
|
and
|
|
.IR Documentation/security/keys-request-key.txt .
|