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

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.

RETURN VALUE

       On success, the ID of the requested keyring.

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

ERRORS

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

VERSIONS

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

STANDARDS

       Linux.

HISTORY

       Linux 2.6.10.