---
name: "KEYCTL_NEGATE"
section: "2const"
platform: "linux"
package: "man-pages"
version: "6.19-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/KEYCTL_INSTANTIATE"
---

# KEYCTL\_NEGATE(2const)

key instantiation functions

Part of [KEYCTL\_INSTANTIATE(2const)](/KEYCTL_INSTANTIATE/2const.md).

## 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)](/KEYCTL_LINK/2const.md), 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)](/request-key/8.md)-style program. See [**request\_key**(2)](/request_key/2.md) 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)](/iovec/3type.md)).

-

  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)](/KEYCTL_LINK/2const.md), 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)](/request-key/8.md)-style program. See [**request\_key**(2)](/request_key/2.md).

-

  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)](/request-key/8.md)-style program. See [**request\_key**(2)](/request_key/2.md) 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/3.md), [**keyctl\_instantiate\_iov**(3)](/keyctl_instantiate_iov/3.md), [**keyctl\_negate**(3)](/keyctl_negate/3.md), and [**keyctl\_reject**(3)](/keyctl_reject/3.md).

## 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/2.md), [**keyctl\_instantiate**(3)](/keyctl_instantiate/3.md), [**keyctl\_instantiate\_iov**(3)](/keyctl_instantiate_iov/3.md), [**keyctl\_negate**(3)](/keyctl_negate/3.md), [**keyctl\_reject**(3)](/keyctl_reject/3.md)