Ubuntu Manpage: KEYCTL_RESTRICT_KEYRING - restrict keys that may be linked to a keyring

NAME

       KEYCTL_RESTRICT_KEYRING - restrict keys that may be linked to a keyring

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_RESTRICT_KEYRING, key_serial_t keyring,
                    const char *_Nullable type, const char *restriction);

DESCRIPTION

Apply a key-linking restriction to the keyring with the ID provided in keyring. The caller must have
setattr permission on the key. If type is NULL, any attempt to add a key to the keyring is blocked;
otherwise it contains a pointer to a string with a key type name and restriction contains a pointer to
string that describes the type-specific restriction. As of Linux 4.12, only the type "asymmetric" has
restrictions defined:

builtin_trusted
Allows only keys that are signed by a key linked to the built-in keyring
(".builtin_trusted_keys").

builtin_and_secondary_trusted
Allows only keys that are signed by a key linked to the secondary keyring
(".secondary_trusted_keys") or, by extension, a key in a built-in keyring, as the latter is linked
to the former.

key_or_keyring:key
key_or_keyring:key:chain
If key specifies the ID of a key of type "asymmetric", then only keys that are signed by this key
are allowed.

If key specifies the ID of a keyring, then only keys that are signed by a key linked to this
keyring are allowed.

If ":chain" is specified, keys that are signed by a keys linked to the destination keyring (that
is, the keyring with the ID specified in the keyring argument) are also allowed.

Note that a restriction can be configured only once for the specified keyring; once a restriction is set,
it can't be overridden.

RETURN VALUE

       On success, 0 is returned.

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

ERRORS

       EDEADLK
              The requested keyring restriction would result in a cycle.

       EEXIST keyring already has a restriction set.

       ENOENT The type provided in type argument doesn't support setting key linking restrictions.

       EOPNOTSUPP
              type was "asymmetric", and  the  key  specified  in  the  restriction  specification  provided  in
              restriction has type other than "asymmetric" or "keyring".

VERSIONS

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

STANDARDS

       Linux.

HISTORY

       Linux 4.12.