KEYCTL_ASSUME_AUTHORITY(2const)

NAME

KEYCTL_ASSUME_AUTHORITY - assume the authority to instantiate a key

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_ASSUME_AUTHORITY, key_serial_t key);

DESCRIPTION

Assume (or divest) the authority for the calling thread to instantiate a key.

The key argument specifies either a nonzero key ID to assume authority, or the value 0 to divest authority.

If key is nonzero, then it specifies the ID of an uninstantiated key for which authority is to be assumed. That key can then be instantiated using one of KEYCTL_INSTANTIATE(2const), KEYCTL_INSTANTIATE_IOV(2const), KEYCTL_REJECT(2const), or KEYCTL_NEGATE(2const). Once the key has been instantiated, the thread is automatically divested of authority to instantiate the key.

Authority over a key can be assumed only if the calling thread has present in its keyrings the authorization key that is associated with the specified key. (In other words, the KEYCTL_ASSUME_AUTHORITY operation is available only from a request-key(8)-style program; see request_key(2) for an explanation of how this operation is used.) The caller must have search permission on the authorization key.

If the specified key has a matching authorization key, then the ID of that key is returned. The authorization key can be read (KEYCTL_READ(2const)) to obtain the callout information passed to request_key(2).

If the ID given in key is 0, then the currently assumed authority is cleared (divested), and the value 0 is returned.

The KEYCTL_ASSUME_AUTHORITY mechanism allows a program such as request-key(8) to assume the necessary authority to instantiate a new uninstantiated key that was created as a consequence of a call to request_key(2). For further information, see request_key(2) and the kernel source file Documentation/security/keys-request-key.txt.

RETURN VALUE

On success, either 0, if the ID given was 0, or the ID of the authorization key matching the specified key, if a nonzero key ID was provided.

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

VERSIONS

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

STANDARDS

Linux.

HISTORY

Linux 2.6.16.