Ubuntu Manpage: KEYCTL_SEARCH - search a keyring for a key

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).

RETURN VALUE

       On success, the ID of the key that was found.

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

ERRORS

       EINVAL The size of the description in desc (including the terminating null byte) exceeded 4096 bytes.

VERSIONS

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

STANDARDS

       Linux.

HISTORY

       Linux 2.6.10.