jpayne@68: .\"
jpayne@68: .\" Copyright (C) 2006 Red Hat, Inc. All Rights Reserved.
jpayne@68: .\" Written by David Howells (dhowells@redhat.com)
jpayne@68: .\"
jpayne@68: .\" This program is free software; you can redistribute it and/or
jpayne@68: .\" modify it under the terms of the GNU General Public License
jpayne@68: .\" as published by the Free Software Foundation; either version
jpayne@68: .\" 2 of the License, or (at your option) any later version.
jpayne@68: .\"
jpayne@68: .TH KEYCTL_INSTANTIATE 3 "4 May 2006" Linux "Linux Key Management Calls"
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH NAME
jpayne@68: keyctl_assume_authority, keyctl_instantiate, keyctl_instantiate_iov, keyctl_reject, keyctl_negate \- key instantiation functions
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH SYNOPSIS
jpayne@68: .nf
jpayne@68: .B #include <keyutils.h>
jpayne@68: .sp
jpayne@68: .BI "long keyctl_assume_authority(key_serial_t " key ");"
jpayne@68: .sp
jpayne@68: .BI "long keyctl_instantiate(key_serial_t " key ", const void *" payload ,
jpayne@68: .BI "size_t " plen ", key_serial_t " keyring ");"
jpayne@68: .sp
jpayne@68: .BI "long keyctl_instantiate_iov(key_serial_t " key ,
jpayne@68: .BI "const struct iovec *" payload_iov ", unsigned " ioc ,
jpayne@68: .BI "key_serial_t " keyring ");"
jpayne@68: .sp
jpayne@68: .BI "long keyctl_negate(key_serial_t " key ", unsigned " timeout ,
jpayne@68: .BI "key_serial_t " keyring ");"
jpayne@68: .sp
jpayne@68: .BI "long keyctl_reject(key_serial_t " key ", unsigned " timeout ,
jpayne@68: .BI "unsigned " error ", key_serial_t " keyring ");"
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH DESCRIPTION
jpayne@68: .BR keyctl_assume_authority ()
jpayne@68: assumes the authority for the calling thread to deal with and instantiate the
jpayne@68: specified uninstantiated
jpayne@68: .IR key .
jpayne@68: .P
jpayne@68: The calling thread must have the appropriate authorisation key resident in one
jpayne@68: of its keyrings for this to succeed, and that authority must not have been
jpayne@68: revoked.
jpayne@68: .P
jpayne@68: The authorising key is allocated by
jpayne@68: .BR request_key()
jpayne@68: when it needs to invoke
jpayne@68: userspace to generate a key for the requesting process.  This is then attached
jpayne@68: to one of the keyrings of the userspace process to which the task of
jpayne@68: instantiating the key is given:
jpayne@68: .IP
jpayne@68: requester -> request_key() -> instantiator
jpayne@68: .P
jpayne@68: Calling this function modifies the way
jpayne@68: .BR request_key ()
jpayne@68: works when called thereafter by the calling (instantiator) thread; once the
jpayne@68: authority is assumed, the keyrings of the initial process are added to the
jpayne@68: search path, using the initial process's UID, GID, groups and security
jpayne@68: context.
jpayne@68: .P
jpayne@68: If a thread has multiple instantiations to deal with, it may call this
jpayne@68: function to change the authorisation key currently in effect.  Supplying a
jpayne@68: .B zero
jpayne@68: .I key
jpayne@68: de-assumes the currently assumed authority.
jpayne@68: .P
jpayne@68: .B NOTE!
jpayne@68: This is a per-thread setting and not a per-process setting so that a
jpayne@68: multithreaded process can be used to instantiate several keys at once.
jpayne@68: .P
jpayne@68: .BR keyctl_instantiate ()
jpayne@68: instantiates the payload of an uninstantiated key from the data specified.
jpayne@68: .I payload
jpayne@68: and
jpayne@68: .I plen
jpayne@68: specify the data for the new payload.
jpayne@68: .I payload
jpayne@68: may be NULL and
jpayne@68: .I plen
jpayne@68: may be zero if the key type permits that.  The key type may reject the data if
jpayne@68: it's in the wrong format or in some other way invalid.
jpayne@68: .P
jpayne@68: .BR keyctl_instantiate_iov ()
jpayne@68: is similar, but the data is passed in an array of iovec structs instead of in
jpayne@68: a flat buffer.
jpayne@68: .I payload_iov
jpayne@68: points to the base of the array and
jpayne@68: .I ioc
jpayne@68: indicates how many elements there are.
jpayne@68: .I payload_iov
jpayne@68: may be NULL or
jpayne@68: .I ioc
jpayne@68: may be zero to indicate that no data is being supplied.
jpayne@68: .P
jpayne@68: .BR keyctl_reject ()
jpayne@68: marks a key as negatively instantiated and sets the expiration timer on it.
jpayne@68: .I timeout
jpayne@68: specifies the lifetime of the key in seconds.
jpayne@68: .I error
jpayne@68: specifies the error to be returned when a search hits the key (this is
jpayne@68: typically
jpayne@68: .BR EKEYREJECTED ", " EKEYREVOKED " or " EKEYEXPIRED ")."
jpayne@68: Note that
jpayne@68: .BR keyctl_reject ()
jpayne@68: falls back to
jpayne@68: .BR keyctl_negate ()
jpayne@68: if the kernel does not
jpayne@68: support it.
jpayne@68: .P
jpayne@68: .BR keyctl_negate ()
jpayne@68: as
jpayne@68: .BR keyctl_reject ()
jpayne@68: with an error code of
jpayne@68: .IB ENOKEY .
jpayne@68: .P
jpayne@68: Only a key for which authority has been assumed may be instantiated or
jpayne@68: negatively instantiated, and once instantiated, the authorisation key will be
jpayne@68: revoked and the requesting process will be able to resume.
jpayne@68: .P
jpayne@68: The destination
jpayne@68: .IR keyring ,
jpayne@68: if given, is assumed to belong to the initial requester, and not the
jpayne@68: instantiating process.  Therefore, the special keyring IDs refer to the
jpayne@68: requesting process's keyrings, not the caller's, and the requester's UID,
jpayne@68: etc. will be used to access them.
jpayne@68: .P
jpayne@68: The destination keyring can be
jpayne@68: .B zero
jpayne@68: if no extra link is desired.
jpayne@68: .P
jpayne@68: The requester, not the caller, must have
jpayne@68: .B write
jpayne@68: permission on the destination for a link to be made there.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH RETURN VALUE
jpayne@68: On success
jpayne@68: .BR keyctl_instantiate ()
jpayne@68: returns
jpayne@68: .BR 0 .
jpayne@68: On error, the value
jpayne@68: .B -1
jpayne@68: will be returned and
jpayne@68: .I errno
jpayne@68: will have been set to an appropriate error.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH ERRORS
jpayne@68: .TP
jpayne@68: .B ENOKEY
jpayne@68: The key or keyring specified is invalid.
jpayne@68: .TP
jpayne@68: .B EKEYEXPIRED
jpayne@68: The keyring specified has expired.
jpayne@68: .TP
jpayne@68: .B EKEYREVOKED
jpayne@68: The key or keyring specified had been revoked, or the authorisation has been
jpayne@68: revoked.
jpayne@68: .TP
jpayne@68: .B EINVAL
jpayne@68: The payload data was invalid.
jpayne@68: .TP
jpayne@68: .B ENOMEM
jpayne@68: Insufficient memory to store the new payload or to expand the destination
jpayne@68: keyring.
jpayne@68: .TP
jpayne@68: .B EDQUOT
jpayne@68: The key quota for the key's user would be exceeded by increasing the size of
jpayne@68: the key to accommodate the new payload or the key quota for the keyring's user
jpayne@68: would be exceeded by expanding the destination keyring.
jpayne@68: .TP
jpayne@68: .B EACCES
jpayne@68: The key exists, but is not
jpayne@68: .B writable
jpayne@68: by the requester.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH LINKING
jpayne@68: This is a library function that can be found in
jpayne@68: .IR libkeyutils .
jpayne@68: When linking,
jpayne@68: .B \-lkeyutils
jpayne@68: should be specified to the linker.
jpayne@68: .\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
jpayne@68: .SH SEE ALSO
jpayne@68: .ad l
jpayne@68: .nh
jpayne@68: .BR keyctl (1),
jpayne@68: .BR add_key (2),
jpayne@68: .BR keyctl (2),
jpayne@68: .BR request_key (2),
jpayne@68: .BR keyctl (3),
jpayne@68: .BR keyrings (7),
jpayne@68: .BR keyutils (7),
jpayne@68: .BR request\-key (8)