Debian Codegraph @

upstream/fedora-44/man2const/KEYCTL_RESTRICT_KEYRING.2const

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