Debian Codegraph @

upstream/debian-unstable/man2/KEYCTL_RESTRICT_KEYRING.2const

raw
1 .\" Copyright 2016, Michael Kerrisk <[email protected]>
2 .\" Copyright 2016, Eugene Syromyatnikov <[email protected]>
3 .\" Copyright, the authors of the Linux man-pages project
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH KEYCTL_RESTRICT_KEYRING 2const 2026-02-08 "Linux man-pages 6.18"
8 .SH NAME
9 KEYCTL_RESTRICT_KEYRING
10 \-
11 restrict keys that may be linked to a keyring
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <linux/keyctl.h>" " /* Definition of " KEY* " constants */"
18 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
19 .B #include <unistd.h>
20 .P
21 .BI "long syscall(SYS_keyctl, KEYCTL_RESTRICT_KEYRING, key_serial_t " keyring ,
22 .BI " const char *_Nullable " type ", const char *" restriction );
23 .fi
24 .SH DESCRIPTION
25 Apply a key-linking restriction to the keyring with the ID provided in
26 .IR keyring .
27 The caller must have
28 .I setattr
29 permission on the key.
30 If
31 .I type
32 is NULL, any attempt to add a key to the keyring is blocked;
33 otherwise it contains a pointer to a string with a key type name and
34 .I restriction
35 contains a pointer to string that describes the type-specific restriction.
36 As of Linux 4.12, only the type "asymmetric" has restrictions defined:
37 .TP
38 .B builtin_trusted
39 Allows only keys that are signed by a key linked to the built-in keyring
40 (".builtin_trusted_keys").
41 .TP
42 .B builtin_and_secondary_trusted
43 Allows only keys that are signed by a key linked to the secondary keyring
44 (".secondary_trusted_keys") or, by extension, a key in a built-in keyring,
45 as the latter is linked to the former.
46 .TP
47 .BI key_or_keyring: key
48 .TQ
49 .BI key_or_keyring: key :chain
50 If
51 .I key
52 specifies the ID of a key of type "asymmetric",
53 then only keys that are signed by this key are allowed.
54 .IP
55 If
56 .I key
57 specifies the ID of a keyring,
58 then only keys that are signed by a key linked
59 to this keyring are allowed.
60 .IP
61 If ":chain" is specified, keys that are signed by a keys linked to the
62 destination keyring (that is, the keyring with the ID specified in the
63 .I keyring
64 argument) are also allowed.
65 .P
66 Note that a restriction can be configured only once for the specified keyring;
67 once a restriction is set, it can't be overridden.
68 .SH RETURN VALUE
69 On success,
70 0 is returned.
71 .P
72 On error, \-1 is returned, and
73 .I errno
74 is set to indicate the error.
75 .SH ERRORS
76 .TP
77 .B EDEADLK
78 The requested keyring restriction would result in a cycle.
79 .TP
80 .B EEXIST
81 .I keyring
82 already has a restriction set.
83 .TP
84 .B ENOENT
85 The type provided in
86 .I type
87 argument doesn't support setting key linking restrictions.
88 .TP
89 .B EOPNOTSUPP
90 .I type
91 was "asymmetric",
92 and the key specified in the restriction specification provided in
93 .I restriction
94 has type other than "asymmetric" or "keyring".
95 .SH VERSIONS
96 A wrapper is provided in the
97 .I libkeyutils
98 library:
99 .BR keyctl_restrict_keyring (3).
100 .SH STANDARDS
101 Linux.
102 .SH HISTORY
103 Linux 4.12.
104 .\" commit 6563c91fd645556c7801748f15bc727c77fcd311
105 .\" commit 7228b66aaf723a623e578aa4db7d083bb39546c9
106 .SH SEE ALSO
107 .BR keyctl (2),
108 .BR keyctl_restrict_keyring (3)