KEYCTL_READ(2const)

NAME

KEYCTL_READ - read 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_READ, key_serial_t key,
             char buf[_Nullable .size], size_t size);

DESCRIPTION

Read the payload data of a key.

The ID of the key whose payload is to be read is specified in key. This can be the ID of an existing key, or any of the special key IDs listed for KEYCTL_GET_KEYRING_ID(2const).

The payload is placed in the buffer pointed by buf; the size of that buffer must be specified in size.

The returned data will be processed for presentation according to the key type. For example, a keyring will return an array of key_serial_t entries representing the IDs of all the keys that are linked to it. The user key type will return its data as is.

If buf is not NULL, as much of the payload data as will fit is copied into the buffer. On a successful return, the return value is always the total size of the payload data. To determine whether the buffer was of sufficient size, check to see that the return value is less than or equal to the value supplied in size.

The key must either grant the caller read permission, or grant the caller search permission when searched for from the process keyrings (i.e., the key is possessed).