Debian Codegraph @

upstream/fedora-44/man2/landlock_create_ruleset.2

raw
1 .\" Copyright © 2017-2020 Mickaël Salaün <[email protected]>
2 .\" Copyright © 2019-2020 ANSSI
3 .\" Copyright © 2021 Microsoft Corporation
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH landlock_create_ruleset 2 2024-11-26 "Linux man-pages 6.13"
8 .SH NAME
9 landlock_create_ruleset \- create a new Landlock ruleset
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ,\~ \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <linux/landlock.h>" " /* Definition of " LANDLOCK_* " constants */"
16 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
17 .B #include <unistd.h>
18 .P
19 .B int syscall(SYS_landlock_create_ruleset,
20 .BI " const struct landlock_ruleset_attr *" attr ,
21 .BI " size_t " size " , uint32_t " flags );
22 .fi
23 .SH DESCRIPTION
24 A Landlock ruleset identifies a set of rules (i.e., actions on objects).
25 This
26 .BR landlock_create_ruleset ()
27 system call creates a new file descriptor
28 which identifies a ruleset.
29 This file descriptor can then be used by
30 .BR landlock_add_rule (2)
31 and
32 .BR landlock_restrict_self (2).
33 See
34 .BR landlock (7)
35 for a global overview.
36 .P
37 .I attr
38 specifies the properties of the new ruleset.
39 It points to the following structure:
40 .IP
41 .in +4n
42 .EX
43 struct landlock_ruleset_attr {
44 __u64 handled_access_fs;
45 __u64 handled_access_net;
46 };
47 .EE
48 .in
49 .IP
50 .I handled_access_fs
51 is a bitmask of handled filesystem actions
52 (see
53 .B Filesystem actions
54 in
55 .BR landlock (7)).
56 .IP
57 .I handled_access_net
58 is a bitmask of handled network actions
59 (see
60 .B Network actions
61 in
62 .BR landlock (7)).
63 .IP
64 This structure defines a set of
65 .IR "handled access rights" ,
66 a set of actions on different object types,
67 which should be denied by default
68 when the ruleset is enacted.
69 Vice versa,
70 access rights that are not specifically listed here
71 are not going to be denied by this ruleset when it is enacted.
72 .IP
73 For historical reasons, the
74 .B LANDLOCK_ACCESS_FS_REFER
75 right is always denied by default,
76 even when its bit is not set in
77 .IR handled_access_fs .
78 In order to add new rules with this access right,
79 the bit must still be set explicitly
80 (see
81 .B Filesystem actions
82 in
83 .BR landlock (7)).
84 .IP
85 The explicit listing of
86 .I handled access rights
87 is required for backwards compatibility reasons.
88 In most use cases,
89 processes that use Landlock will
90 .I handle
91 a wide range or all access rights that they know about at build time
92 (and that they have tested with a kernel that supported them all).
93 .IP
94 This structure can grow in future Landlock versions.
95 .P
96 .I size
97 must be specified as
98 .I sizeof(struct landlock_ruleset_attr)
99 for compatibility reasons.
100 .P
101 .I flags
102 must be 0 if
103 .I attr
104 is used.
105 Otherwise,
106 .I flags
107 can be set to:
108 .TP
109 .B LANDLOCK_CREATE_RULESET_VERSION
110 If
111 .I attr
112 is NULL and
113 .I size
114 is 0, then the returned value is the highest supported Landlock ABI version
115 (starting at 1).
116 This version can be used for a best-effort security approach,
117 which is encouraged when user space is not pinned to a specific kernel
118 version.
119 All features documented in these man pages are available with the version
120 1.
121 .SH RETURN VALUE
122 On success,
123 .BR landlock_create_ruleset ()
124 returns a new Landlock ruleset file descriptor,
125 or a Landlock ABI version,
126 according to
127 .IR flags .
128 On error,
129 \-1 is returned and
130 .I errno
131 is set to indicate the error.
132 .SH ERRORS
133 .BR landlock_create_ruleset ()
134 can fail for the following reasons:
135 .TP
136 .B EOPNOTSUPP
137 Landlock is supported by the kernel but disabled at boot time.
138 .TP
139 .B EINVAL
140 Unknown
141 .IR flags ,
142 or unknown access, or too small
143 .IR size .
144 .TP
145 .B E2BIG
146 .I size
147 is too big.
148 .TP
149 .B EFAULT
150 .I attr
151 was not a valid address.
152 .TP
153 .B ENOMSG
154 Empty accesses (i.e.,
155 .I attr
156 did not specify any access rights to restrict).
157 .SH STANDARDS
158 Linux.
159 .SH HISTORY
160 Linux 5.13.
161 .SH EXAMPLES
162 See
163 .BR landlock (7).
164 .SH SEE ALSO
165 .BR landlock_add_rule (2),
166 .BR landlock_restrict_self (2),
167 .BR landlock (7)