.\" Copyright 2016, Michael Kerrisk <mtk.manpages@gmail.com>
.\" Copyright 2016, Eugene Syromyatnikov <evgsyr@gmail.com>
.\" A very few fragments remain from an earlier version of this page
.\" written by David Howells (dhowells@redhat.com)
.\" Copyright 2024, Alejandro Colomar <alx@kernel.org>
.\"
.\" SPDX-License-Identifier: Linux-man-pages-copyleft
.\"
.TH KEYCTL_RESTRICT_KEYRING 2const 2024-08-21 "Linux man-pages 6.10"
.SH NAME
KEYCTL_RESTRICT_KEYRING
\-
restrict keys that may be linked to a keyring
.SH LIBRARY
Standard C library
.RI ( libc ,\~ \-lc )
.SH SYNOPSIS
.nf
.BR "#include <linux/keyctl.h>" "  /* Definition of " KEY* " constants */"
.BR "#include <sys/syscall.h>" "   /* Definition of " SYS_* " constants */"
.B #include <unistd.h>
.P
.BI "long syscall(SYS_keyctl, KEYCTL_RESTRICT_KEYRING, key_serial_t " keyring ,
.BI "             const char *_Nullable " type ", const char *" restriction );
.fi
.SH DESCRIPTION
Apply a key-linking restriction to the keyring with the ID provided in
.IR keyring .
The caller must have
.I setattr
permission on the key.
If
.I 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
.I restriction
contains a pointer to string that describes the type-specific restriction.
As of Linux 4.12, only the type "asymmetric" has restrictions defined:
.TP
.B builtin_trusted
Allows only keys that are signed by a key linked to the built-in keyring
(".builtin_trusted_keys").
.TP
.B 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.
.TP
.BI key_or_keyring: key
.TQ
.BI key_or_keyring: key :chain
If
.I key
specifies the ID of a key of type "asymmetric",
then only keys that are signed by this key are allowed.
.IP
If
.I key
specifies the ID of a keyring,
then only keys that are signed by a key linked
to this keyring are allowed.
.IP
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
.I keyring
argument) are also allowed.
.P
Note that a restriction can be configured only once for the specified keyring;
once a restriction is set, it can't be overridden.
.SH RETURN VALUE
On success,
0 is returned.
.P
On error, \-1 is returned, and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EDEADLK
The requested keyring restriction would result in a cycle.
.TP
.B EEXIST
.I keyring
already has a restriction set.
.TP
.B ENOENT
The type provided in
.I type
argument doesn't support setting key linking restrictions.
.TP
.B EOPNOTSUPP
.I type
was "asymmetric",
and the key specified in the restriction specification provided in
.I restriction
has type other than "asymmetric" or "keyring".
.SH VERSIONS
A wrapper is provided in the
.I libkeyutils
library:
.BR keyctl_restrict_keyring (3).
.SH STANDARDS
Linux.
.SH HISTORY
Linux 4.12.
.\" commit 6563c91fd645556c7801748f15bc727c77fcd311
.\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
.SH SEE ALSO
.BR keyctl (2),
.BR keyctl_restrict_keyring (3)