# KEYCTL_INSTANTIATE

## NAME



           KEYCTL_INSTANTIATE, KEYCTL_INSTANTIATE_IOV, KEYCTL_NEGATE,
           KEYCTL_REJECT - key instantiation functions
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <linux/keyctl.h>  **/* Definition of **KEY*** constants */
           **#include <sys/syscall.h>   **/* Definition of **SYS_*** constants */
           **#include <unistd.h>**
    
           **long syscall(** size_t n;
                        **SYS_keyctl, KEYCTL_INSTANTIATE, key_serial_t** _key_**,**
                        **const void** _payload_**[**_n_**], size_t** _n_**,**
                        **key_serial_t** _keyring_**);**
           **long syscall(** size_t n;
                        **SYS_keyctl, KEYCTL_INSTANTIATE_IOV, key_serial_t** _key_**,**
                        **const struct iovec** _payload_**[**_n_**], unsigned int** _n_**,**
                        **key_serial_t** _keyring_**);**
           **long syscall(SYS_keyctl, KEYCTL_NEGATE, key_serial_t** _key_**,**
                        **unsigned int** _timeout_**, key_serial_t** _keyring_**);**
           **long syscall(SYS_keyctl, KEYCTL_REJECT, key_serial_t** _key_**,**
                        **unsigned int** _timeout_**, int** _error_**, key_serial_t** _keyring_**);**
    


## DESCRIPTION



           **KEYCTL_INSTANTIATE**
                  (Positively) instantiate an uninstantiated key with a
                  specified payload.
    
                  The ID of the key to be instantiated is provided in _key_.
    
                  The key payload is specified in the buffer pointed to by
                  _payload_ ; the size of that buffer is specified in _n_.
    
                  The payload may be a null pointer and the buffer size may
                  be 0 if this is supported by the key type (e.g., it is a
                  keyring).
    
                  The operation may be fail if the payload data is in the
                  wrong format or is otherwise invalid.
    
                  If _keyring_ is nonzero, then, subject to the same
                  constraints and rules as KEYCTL_LINK(2const), the
                  instantiated key is linked into the keyring whose ID
                  specified in _keyring_.
    
                  The caller must have the appropriate authorization key, and
                  once the uninstantiated key has been instantiated, the
                  authorization key is revoked.  In other words, this
                  operation is available only from a request-key(8)-style
                  program.  See request_key(2) for an explanation of
                  uninstantiated keys and key instantiation.
    
           **KEYCTL_INSTANTIATE_IOV**
                  Instantiate an uninstantiated key with a payload specified
                  via a vector of buffers.
    
                  This operation is the same as **KEYCTL_INSTANTIATE** , but the
                  payload data is specified as an array of _iovec_ structures
                  (see iovec(3type)).
    
                  The pointer to the payload vector is specified in _payload_.
                  The number of items in the vector is specified in _n_.
    
                  The _key_ and _keyring_ are interpreted as for
                  **KEYCTL_INSTANTIATE**.
    
           **KEYCTL_NEGATE**
                  Negatively instantiate an uninstantiated key.
    
                  This operation is equivalent to the call:
    
                      keyctl(KEYCTL_REJECT, key, timeout, ENOKEY, keyring);
    
           **KEYCTL_REJECT**
                  Mark a key as negatively instantiated and set an expiration
                  timer on the key.  This operation provides a superset of
                  the functionality of the earlier **KEYCTL_NEGATE** operation.
    
                  The ID of the key that is to be negatively instantiated is
                  specified in _key_.  The _timeout_ argument specifies the
                  lifetime of the key, in seconds.  The _error_ argument
                  specifies the error to be returned when a search hits this
                  key; typically, this is one of **EKEYREJECTED** , **EKEYREVOKED** ,
                  or **EKEYEXPIRED**.
    
                  If _keyring_ is nonzero, then, subject to the same
                  constraints and rules as KEYCTL_LINK(2const), the
                  negatively instantiated key is linked into the keyring
                  whose ID is specified in _keyring_.
    
                  The caller must have the appropriate authorization key.  In
                  other words, this operation is available only from a
                  request-key(8)-style program.  See request_key(2).
    
                  The caller must have the appropriate authorization key, and
                  once the uninstantiated key has been instantiated, the
                  authorization key is revoked.  In other words, this
                  operation is available only from a request-key(8)-style
                  program.  See request_key(2) for an explanation of
                  uninstantiated keys and key instantiation.
    


## RETURN VALUE



           On success, 0 is returned.
    
           On error, -1 is returned, and _errno_ is set to indicate the error.
    


## VERSIONS



           Wrappers are provided in the _libkeyutils_ library:
           keyctl_instantiate(3), keyctl_instantiate_iov(3),
           keyctl_negate(3), and keyctl_reject(3).
    


## STANDARDS



           Linux.
    


* * *