KEYCTL_GET_PERSISTENT(2const)

NAME

KEYCTL_GET_PERSISTENT - get the persistent keyring for a user

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_PERSISTENT, uid_t uid,
             key_serial_t keyring);

DESCRIPTION

Get the persistent keyring (persistent-keyring(7)) for a specified user and link it to a specified keyring.

The user ID is specified in uid. If the value -1 is specified, the caller's real user ID is used. The ID of the destination keyring is specified in keyring.

The caller must have the CAP_SETUID capability in its user namespace in order to fetch the persistent keyring for a user ID that does not match either the real or effective user ID of the caller.

If the call is successful, a link to the persistent keyring is added to the keyring whose ID was specified in keyring.

The caller must have write permission on the keyring.

The persistent keyring will be created by the kernel if it does not yet exist.

Each time the KEYCTL_GET_PERSISTENT operation is performed, the persistent keyring will have its expiration timeout reset to the value in:

/proc/sys/kernel/keys/persistent_keyring_expiry

Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected.

Persistent keyrings were added in Linux 3.13.

RETURN VALUE

On success, the ID of the persistent keyring.

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

ERRORS

EPERM: uid specified a UID other than the calling thread's real or effective UID, and the caller did not have the CAP_SETUID capability.

VERSIONS

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

STANDARDS

Linux.

HISTORY

Linux 3.13.