KEYCTL_GET_KEYRING_ID(2const)

NAME

KEYCTL_GET_KEYRING_ID - map a special key ID to a real key ID for this process

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_GET_KEYRING_ID, key_serial_t key,
             int arg3);

DESCRIPTION

Map a special key ID to a real key ID for this process.

This operation looks up the special key whose ID is provided in key. If the special key is found, the ID of the corresponding real key is returned as the function result. The following values may be specified in key:

KEY_SPEC_THREAD_KEYRING: This specifies the calling thread's thread-specific keyring. See thread-keyring(7).
KEY_SPEC_PROCESS_KEYRING: This specifies the caller's process-specific keyring. See process-keyring(7).
KEY_SPEC_SESSION_KEYRING: This specifies the caller's session-specific keyring. See session-keyring(7).
KEY_SPEC_USER_KEYRING: This specifies the caller's UID-specific keyring. See user-keyring(7).
KEY_SPEC_USER_SESSION_KEYRING: This specifies the caller's UID-session keyring. See user-session-keyring(7).
KEY_SPEC_REQKEY_AUTH_KEY (since Linux 2.6.16): This specifies the authorization key created by request_key(2) and passed to the process it spawns to generate a key. This key is available only in a request-key(8)-style program that was passed an authorization key by the kernel and ceases to be available once the requested key has been instantiated; see request_key(2).
KEY_SPEC_REQUESTOR_KEYRING (since Linux 2.6.29): This specifies the key ID for the request_key(2) destination keyring. This keyring is available only in a request-key(8)-style program that was passed an authorization key by the kernel and ceases to be available once the requested key has been instantiated; see request_key(2).

The behavior if the key specified in key does not exist depends on the value of arg3. If arg3 contains a nonzero value, then —if it is appropriate to do so (e.g., when looking up the user, user-session, or session key)— a new key is created and its real key ID returned as the function result. Otherwise, the operation fails with the error ENOKEY.

If a valid key ID is specified in key, and the key exists, then this operation simply returns the key ID. If the key does not exist, the call fails with error ENOKEY.

The caller must have search permission on a keyring in order for it to be found.