KEYCTL_SEARCH(2const)

NAME

KEYCTL_SEARCH - search a keyring for 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_SEARCH, key_serial_t src,
             char *type, char *desc,
             unsigned long dst);

DESCRIPTION

Search for a key in a keyring tree, returning its ID and optionally linking it to a specified keyring.

The tree to be searched is specified by passing the ID of the head keyring in src. The search is performed breadth-first and recursively.

The type and desc arguments specify the key to be searched for: type contains the key type (a null-terminated character string up to 32 bytes in size, including the terminating null byte), and desc contains the description of the key (a null-terminated character string up to 4096 bytes in size, including the terminating null byte).

The source keyring must grant search permission to the caller. When performing the recursive search, only keyrings that grant the caller search permission will be searched. Only keys with for which the caller has search permission can be found.

If the key is found, its ID is returned as the function result.

If the key is found and dst is nonzero, then, subject to the same constraints and rules as KEYCTL_LINK(2const), the key is linked into the keyring whose ID is specified in dst. If the destination keyring specified in dst already contains a link to a key that has the same type and description, then that link will be displaced by a link to the key found by this operation.

Instead of valid existing keyring IDs, the source (src) and destination (dst) keyrings can be one of the special keyring IDs listed under KEYCTL_GET_KEYRING_ID(2const).