request-key

request-key <type> <description> [<callout-info>]

<type>
    The type of key to be requested (e.g., 'user', 'logon', 'big_key'). This determines the key management policy and data format.

<description>
    A string describing the key, which is used by the kernel to look up the key. Its interpretation depends on the key type.

<callout-info> (optional)
    An optional, arbitrary string that provides additional information to the helper program for instantiating the key. For example, it might contain a filename or a network address.

The `request-key` command is a crucial user-space helper program for the Linux kernel's key retention service. Its primary function is to instantiate, find, or otherwise obtain a key when the kernel or a user-space program initiates a key request that cannot be immediately fulfilled from existing keyrings. When the kernel attempts to look up a key and fails to find it, it can invoke `request-key` through a pre-configured mechanism (often via the request_key() syscall, or through the keyctl_request_key() library function in user space).

Upon invocation, `request-key` receives parameters detailing the requested key's type, description, and an optional callout-info string. It then consults its configuration file, typically /etc/request-key.conf, to determine the appropriate action. This action might involve executing another program, reading a key from a file, or dynamically generating a key based on the request's parameters. The returned key ID is then passed back to the kernel, allowing the requesting process to use the newly instantiated key. This mechanism is fundamental for services that rely on dynamically available keys, such as AFS or user-defined authentication systems, ensuring secure and flexible key management within the Linux environment.

The security of the `request-key` mechanism heavily relies on its configuration in /etc/request-key.conf. If not properly secured, misconfigurations could lead to privilege escalation or unauthorized key instantiation. It's critical to ensure that the helper programs executed by `request-key` are trusted, properly sandboxed, and handle their inputs securely.

Since `request-key` is often invoked by the kernel, errors or infinite loops in the configured helper scripts can severely impact system stability and performance. Debugging issues with `request-key` can be challenging as the initial call often originates from kernel space.

The behavior of `request-key` is primarily controlled by the configuration file /etc/request-key.conf. This file contains rules that map key types and descriptions to specific helper programs or actions. Each rule specifies how a requested key should be handled, potentially by executing a script or program that generates the key. The configuration allows for highly flexible and context-dependent key management.

`request-key` is not typically run directly by users. Instead, it's a kernel helper. The kernel's request_key() syscall, when unable to find a key, looks for a `request-key` helper configured via /proc/sys/kernel/keys/request_key_helper. This allows the kernel to delegate complex key lookup and instantiation logic to user-space, which can access filesystems, network resources, and other user-space services.

The Linux kernel key retention service, which `request-key` is an integral part of, was introduced relatively early in the 2.6 kernel series. It aimed to provide a generic, secure, and extensible mechanism for managing cryptographic and other arbitrary keys within the kernel and across user-space applications. The `request-key` helper program was designed alongside this service to enable dynamic key instantiation, allowing applications and kernel components to obtain keys on demand without pre-loading them, thus enhancing flexibility and security. Its design reflects the need for a user-space component to handle complex key acquisition logic that is better suited for user-space programming than kernel modules.

keyctl(1), add_key(2), keyrings(7), request-key.conf(5)