Ubuntu Manpages

KEYCTL_GET_KEYRING_ID

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

Standard C library (libc, -lc)

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

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:

This specifies the calling thread's thread-specific keyring. See thread-keyring(7).
This specifies the caller's process-specific keyring. See process-keyring(7).
This specifies the caller's session-specific keyring. See session-keyring(7).
This specifies the caller's UID-specific keyring. See user-keyring(7).
This specifies the caller's UID-session keyring. See user-session-keyring(7).
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).
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.

On success, the ID of the requested keyring.

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

The key specified in key did not exist, and arg3 was zero (meaning don't create the key if it didn't exist).

A wrapper is provided in the libkeyutils library: keyctl_get_keyring_ID(3).

Linux.

Linux 2.6.10.

keyctl(2), keyctl_get_keyring_ID(3)