KEYCTL_INSTANTIATE(2const)

💖 KEYCTL_INSTANTIATE(2const) — key instantiation functions 💖

okay bestie, sit DOWN, because this is the one where you learn how uninstantiated keys get their whole life together ✨ This is from the Linux man-pages, section 2const (constants), and it's giving "kernel keyring lore" in the best way possible.

---

✨ NAME ✨

KEYCTL_INSTANTIATE, KEYCTL_INSTANTIATE_IOV, KEYCTL_NEGATE, KEYCTL_REJECT — the key instantiation functions, aka the four ways to tell a baby key what it's gonna be when it grows up 🐣

---

📚 LIBRARY 📚

Standard C library (libc, -lc) — yep, plain old libc, no extra drama 💅

---

🎀 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);

like yes, that's four syscall() shapes and they are all ICONIC in their own way 🫶

---

🌸 DESCRIPTION 🌸

💫 KEYCTL_INSTANTIATE 💫

(Positively) instantiate an uninstantiated key with a specified payload. It's the glow-up moment ✨

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 the key type supports it (e.g., it's a keyring) — so don't just assume it's fine, it's key-type-dependent, ngl.

The operation may 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 is 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. It's giving "invite only, and the invite self-destructs" 💀

🦋 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)). Scatter-gather but make it keys, periodt.

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. (Sometimes the answer is no, and that's valid 💅)

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 — so it's the deluxe edition, the director's cut, the upgrade 🎬

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.

😭 not the manpage saying the authorization-key thing twice in a row — we keep both, because the original keeps both, and we do not edit the source material. Respect the text, bestie.

---

🌈 RETURN VALUE 🌈

On success, 0 is returned. 🎉

On error, -1 is returned, and errno is set to indicate the error. classic.

---

⭐ VERSIONS ⭐

Wrappers are provided in the libkeyutils library: keyctl_instantiate(3), keyctl_instantiate_iov(3), keyctl_negate(3), and keyctl_reject(3). So like, you don't have to rawdog the syscall, the wrappers exist ✨

---

👑 STANDARDS 👑

Linux. That's it. That's the standard. 🐧

---

🕰️ HISTORY 🕰️

KEYCTL_INSTANTIATE KEYCTL_NEGATE

• Linux 2.6.10.

KEYCTL_INSTANTIATE_IOV KEYCTL_REJECT

• Linux 2.6.39.

the way these went from 2.6.10 to 2.6.39, a whole era of glow-up 💖

---

🔗 SEE ALSO 🔗

• keyctl(2)
• keyctl_instantiate(3)
• keyctl_instantiate_iov(3)
• keyctl_negate(3)
• keyctl_reject(3)

---

and that's the whole page, bestie 🫶 written up in Linux man-pages 6.20, dated 2026-02-08, for the KEYCTL_INSTANTIATE(2const) page — go instantiate something (or reject it, honestly, both are slay) 💅✨