# keyctl_instantiate

## NAME



           keyctl_assume_authority, keyctl_instantiate,
           keyctl_instantiate_iov, keyctl_reject, keyctl_negate - key
           instantiation functions
    


## SYNOPSIS



           **#include <keyutils.h>**
    
           **long keyctl_assume_authority(key_serial_t** _key_**);**
    
           **long keyctl_instantiate(key_serial_t** _key_**, const void ***_payload_**,**
           **size_t** _plen_**, key_serial_t** _keyring_**);**
    
           **long keyctl_instantiate_iov(key_serial_t** _key_**,**
           **const struct iovec ***_payload_iov_**, unsigned** _ioc_**,**
           **key_serial_t** _keyring_**);**
    
           **long keyctl_negate(key_serial_t** _key_**, unsigned** _timeout_**,**
           **key_serial_t** _keyring_**);**
    
           **long keyctl_reject(key_serial_t** _key_**, unsigned** _timeout_**,**
           **unsigned** _error_**, key_serial_t** _keyring_**);**
    


## DESCRIPTION



           **keyctl_assume_authority**() assumes the authority for the calling
           thread to deal with and instantiate the specified uninstantiated
           _key_.
    
           The calling thread must have the appropriate authorisation key
           resident in one of its keyrings for this to succeed, and that
           authority must not have been revoked.
    
           The authorising key is allocated by **request_key()** when it needs to
           invoke userspace to generate a key for the requesting process.
           This is then attached to one of the keyrings of the userspace
           process to which the task of instantiating the key is given:
    
                  requester -> request_key() -> instantiator
    
           Calling this function modifies the way **request_key**() works when
           called thereafter by the calling (instantiator) thread; once the
           authority is assumed, the keyrings of the initial process are
           added to the search path, using the initial process's UID, GID,
           groups and security context.
    
           If a thread has multiple instantiations to deal with, it may call
           this function to change the authorisation key currently in effect.
           Supplying a **zero** _key_ de-assumes the currently assumed authority.
    
           **NOTE!** This is a per-thread setting and not a per-process setting
           so that a multithreaded process can be used to instantiate several
           keys at once.
    
           **keyctl_instantiate**() instantiates the payload of an uninstantiated
           key from the data specified.  _payload_ and _plen_ specify the data
           for the new payload.  _payload_ may be NULL and _plen_ may be zero if
           the key type permits that.  The key type may reject the data if
           it's in the wrong format or in some other way invalid.
    
           **keyctl_instantiate_iov**() is similar, but the data is passed in an
           array of iovec structs instead of in a flat buffer.  _payload_iov_
           points to the base of the array and _ioc_ indicates how many
           elements there are.  _payload_iov_ may be NULL or _ioc_ may be zero to
           indicate that no data is being supplied.
    
           **keyctl_reject**() marks a key as negatively instantiated and sets
           the expiration timer on it.  _timeout_ specifies the lifetime of the
           key in seconds.  _error_ specifies the error to be returned when a
           search hits the key (this is typically **EKEYREJECTED** , **EKEYREVOKED**
           or **EKEYEXPIRED**).  Note that **keyctl_reject**() falls back to
           **keyctl_negate**() if the kernel does not support it.
    
           **keyctl_negate**() as **keyctl_reject**() with an error code of _ENOKEY_**.**
    
           Only a key for which authority has been assumed may be
           instantiated or negatively instantiated, and once instantiated,
           the authorisation key will be revoked and the requesting process
           will be able to resume.
    
           The destination _keyring_ , if given, is assumed to belong to the
           initial requester, and not the instantiating process.  Therefore,
           the special keyring IDs refer to the requesting process's
           keyrings, not the caller's, and the requester's UID, etc. will be
           used to access them.
    
           The destination keyring can be **zero** if no extra link is desired.
    
           The requester, not the caller, must have **write** permission on the
           destination for a link to be made there.
    


## RETURN VALUE



           On success **keyctl_instantiate**() returns **0**.  On error, the value **-1**
           will be returned and _errno_ will have been set to an appropriate
           error.
    


## ERRORS



           **ENOKEY** The key or keyring specified is invalid.
    
           **EKEYEXPIRED**
                  The keyring specified has expired.
    
           **EKEYREVOKED**
                  The key or keyring specified had been revoked, or the
                  authorisation has been revoked.
    
           **EINVAL** The payload data was invalid.
    
           **ENOMEM** Insufficient memory to store the new payload or to expand
                  the destination keyring.
    
           **EDQUOT** The key quota for the key's user would be exceeded by
                  increasing the size of the key to accommodate the new
                  payload or the key quota for the keyring's user would be
                  exceeded by expanding the destination keyring.
    
           **EACCES** The key exists, but is not **writable** by the requester.
    


## LINKING



           This is a library function that can be found in _libkeyutils_.  When
           linking, **-lkeyutils** should be specified to the linker.
    


* * *