keyctl

List keys in a specific keyring

$ keyctl list [target_keyring]

$ keyctl list [@us]

$ keyctl add [type_keyring] [key_name] [key_value] [target_keyring]

$ echo -n [key_value] | keyctl padd [type_keyring] [key_name] [target_keyring]

$ keyctl timeout [key_name] [timeout_in_seconds]

$ keyctl read [key_name]

$ keyctl pipe [key_name]

$ keyctl revoke [key_name]

keyctl [options] command [arguments...]

add type description data keyring
    Adds a new key of the specified type and description with provided data to a target keyring.

padd type description keyring
    Adds a key, similar to 'add', but reads the key data from standard input.

link key keyring
    Links an existing key, identified by its ID, to a specified keyring.

unlink key keyring
    Unlinks a key from a keyring. The key is destroyed if it loses all its links.

show
    Displays the IDs and descriptions of the keys in the current process's keyrings.

list keyring
    Lists the keys contained within a specified keyring.

read key
    Reads and displays the data associated with a specified key. Requires read permission on the key.

revoke key
    Revokes a key, immediately making it unusable and eventually destroying it.

chown key uid
    Changes the owner of a key to the specified user ID.

chgrp key gid
    Changes the group of a key to the specified group ID.

setperm key permissions
    Sets the access permissions mask for a key. Permissions are octal values.

session
    Displays the ID of the current process's session keyring. Can also set a new session keyring.

new_session
    Creates a new session keyring for the current process and makes it the default session keyring.

search keyring type description
    Searches for a key with a specific type and description within a keyring tree.

update key data
    Updates the data payload of an existing key. Key type must support updates.

-h, --help
    Displays a brief usage message and exits.

-V, --version
    Displays version information and exits.

keyctl is a utility program for controlling the Linux kernel's key management facility. This facility allows applications to securely store, manage, and share various types of cryptographic keys, authentication tokens, and other security-related data within the kernel. It provides a robust mechanism for managing keys that can be inherited by child processes, linked to various keyrings (e.g., process, thread, session, user-specific), and restricted by permissions and timeouts. Common operations performed by keyctl include adding new keys, linking them to keyrings, unlinking keys, revoking them, displaying key information, and manipulating key permissions and ownership. The key management facility is critical for features like disk encryption (e.g., fscrypt), authenticated communication, and secure credential storage, ensuring keys are handled securely in kernel space, isolated from user-space processes unless explicitly accessed.

• Permissions: Manipulating keys often requires specific permissions (read, write, search, link, setattr) on the keys and keyrings involved. Incorrect permissions can lead to operation failures or security vulnerabilities.
• Key Lifetimes: Keys can have explicit timeouts or can be implicitly destroyed when no longer linked to any keyring or when their owning process exits (for process-specific keyrings). Understanding key lifetimes is crucial to avoid unexpected key expiry or lingering keys.
• Security Implications: Storing sensitive data in the kernel key management facility is generally more secure than user-space, but mishandling keyctl can expose credentials. Always use with caution and follow security best practices.
• Kernel Support: The key management facility and keyctl commands depend on kernel support, which is generally available in modern Linux distributions. Older kernels might have limited functionality.

The key management facility supports various key types, such as 'user' for arbitrary data, 'logon' for authentication tokens, 'trusted' and 'encrypted' for cryptographic keys, and 'keyring' for key collections. Each type has specific properties and behaviors.

Linux provides different types of keyrings: 'process' (inherited by children, destroyed on process exit), 'thread' (specific to a thread), 'session' (specific to a login session, inherited by all processes in the session), 'user' (user-specific, persistent across sessions), and 'user_session' (a user-specific session keyring). Understanding which keyring to use is crucial for key visibility and lifetime.

Keys and keyrings have permission masks similar to file permissions (read, write, execute), but with additional key-specific permissions (search, link, setattr). These permissions determine who can access, modify, or link keys.

The Linux kernel key management facility was introduced by David Howells, with significant development and refinement over time. It was designed to provide a secure and robust mechanism for managing keys and credentials within the kernel, addressing a gap in earlier Linux versions. The keyctl utility was developed as the primary user-space interface to interact with this kernel subsystem, evolving alongside it to support new key types and functionalities. Its usage has grown steadily with the increasing adoption of features like disk encryption (fscrypt, dm-crypt), network authentication, and secure daemon operations that rely on kernel-managed credentials.

add_key(2), request_key(2), keyrings(7), mount(8)