KEYCTL_INSTANTIATE(2const)                          KEYCTL_INSTANTIATE(2const)

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(SYS_keyctl, KEYCTL_INSTANTIATE, key_serial_t key,
                    const void payload[.n], size_t n,
                    key_serial_t keyring);
       long syscall(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.

HISTORY
       KEYCTL_INSTANTIATE
       KEYCTL_NEGATE
              Linux 2.6.10.

       KEYCTL_INSTANTIATE_IOV
       KEYCTL_REJECT
              Linux 2.6.39.

SEE ALSO
       keyctl(2), keyctl_instantiate(3), keyctl_instantiate_iov(3),
       keyctl_negate(3), keyctl_reject(3)

Linux man-pages 6.10              2024-08-21        KEYCTL_INSTANTIATE(2const)