]>
Commit | Line | Data |
---|---|---|
38454e3f MS |
1 | .\" Copyright © 2017-2020 Mickaël Salaün <mic@digikod.net> |
2 | .\" Copyright © 2019-2020 ANSSI | |
3 | .\" Copyright © 2021 Microsoft Corporation | |
4 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
38454e3f | 6 | .\" |
45186a5d | 7 | .TH LANDLOCK 7 2021-06-27 "Linux man-pages (unreleased)" |
38454e3f MS |
8 | .SH NAME |
9 | Landlock \- unprivileged access-control | |
10 | .SH DESCRIPTION | |
11 | Landlock is an access-control system that enables any processes to | |
12 | securely restrict themselves and their future children. | |
13 | Because Landlock is a stackable Linux Security Module (LSM), | |
085a9296 AC |
14 | it makes it possible to create safe security sandboxes |
15 | as new security layers in addition to | |
16 | the existing system-wide access-controls. | |
38454e3f MS |
17 | This kind of sandbox is expected to help mitigate |
18 | the security impact of bugs, | |
19 | and unexpected or malicious behaviors in applications. | |
20 | .PP | |
21 | A Landlock security policy is a set of access rights | |
22 | (e.g., open a file in read-only, make a directory, etc.) | |
23 | tied to a file hierarchy. | |
24 | Such policy can be configured and enforced by processes for themselves | |
25 | using three system calls: | |
26 | .IP \(bu 2 | |
27 | .BR landlock_create_ruleset (2) | |
28 | creates a new ruleset; | |
29 | .IP \(bu | |
30 | .BR landlock_add_rule (2) | |
31 | adds a new rule to a ruleset; | |
32 | .IP \(bu | |
33 | .BR landlock_restrict_self (2) | |
34 | enforces a ruleset on the calling thread. | |
35 | .PP | |
36 | To be able to use these system calls, | |
37 | the running kernel must support Landlock and | |
38 | it must be enabled at boot time. | |
39 | .\" | |
40 | .SS Landlock rules | |
41 | A Landlock rule describes an action on an object. | |
42 | An object is currently a file hierarchy, | |
43 | and the related filesystem actions are defined with access rights (see | |
44 | .BR landlock_add_rule (2)). | |
45 | A set of rules is aggregated in a ruleset, | |
46 | which can then restrict the thread enforcing it, | |
47 | and its future children. | |
48 | .\" | |
49 | .SS Filesystem actions | |
50 | These flags enable to restrict a sandboxed process to a | |
51 | set of actions on files and directories. | |
52 | Files or directories opened before the sandboxing | |
53 | are not subject to these restrictions. | |
54 | See | |
55 | .BR landlock_add_rule (2) | |
56 | and | |
57 | .BR landlock_create_ruleset (2) | |
58 | for more context. | |
59 | .PP | |
60 | A file can only receive these access rights: | |
61 | .TP | |
62 | .B LANDLOCK_ACCESS_FS_EXECUTE | |
63 | Execute a file. | |
64 | .TP | |
65 | .B LANDLOCK_ACCESS_FS_WRITE_FILE | |
66 | Open a file with write access. | |
67 | .TP | |
68 | .B LANDLOCK_ACCESS_FS_READ_FILE | |
69 | Open a file with read access. | |
70 | .PP | |
71 | A directory can receive access rights related to files or directories. | |
72 | The following access right is applied to the directory itself, | |
73 | and the directories beneath it: | |
74 | .TP | |
75 | .B LANDLOCK_ACCESS_FS_READ_DIR | |
76 | Open a directory or list its content. | |
77 | .PP | |
78 | However, | |
79 | the following access rights only apply to the content of a directory, | |
80 | not the directory itself: | |
81 | .TP | |
82 | .B LANDLOCK_ACCESS_FS_REMOVE_DIR | |
83 | Remove an empty directory or rename one. | |
84 | .TP | |
85 | .B LANDLOCK_ACCESS_FS_REMOVE_FILE | |
86 | Unlink (or rename) a file. | |
87 | .TP | |
88 | .B LANDLOCK_ACCESS_FS_MAKE_CHAR | |
89 | Create (or rename or link) a character device. | |
90 | .TP | |
91 | .B LANDLOCK_ACCESS_FS_MAKE_DIR | |
92 | Create (or rename) a directory. | |
93 | .TP | |
94 | .B LANDLOCK_ACCESS_FS_MAKE_REG | |
95 | Create (or rename or link) a regular file. | |
96 | .TP | |
97 | .B LANDLOCK_ACCESS_FS_MAKE_SOCK | |
98 | Create (or rename or link) a UNIX domain socket. | |
99 | .TP | |
100 | .B LANDLOCK_ACCESS_FS_MAKE_FIFO | |
101 | Create (or rename or link) a named pipe. | |
102 | .TP | |
103 | .B LANDLOCK_ACCESS_FS_MAKE_BLOCK | |
104 | Create (or rename or link) a block device. | |
105 | .TP | |
106 | .B LANDLOCK_ACCESS_FS_MAKE_SYM | |
107 | Create (or rename or link) a symbolic link. | |
108 | .\" | |
109 | .SS Layers of file path access rights | |
110 | Each time a thread enforces a ruleset on itself, | |
111 | it updates its Landlock domain with a new layer of policy. | |
085a9296 AC |
112 | Indeed, this complementary policy is composed with the |
113 | potentially other rulesets already restricting this thread. | |
38454e3f MS |
114 | A sandboxed thread can then safely add more constraints to itself with a |
115 | new enforced ruleset. | |
116 | .PP | |
117 | One policy layer grants access to a file path | |
118 | if at least one of its rules encountered on the path grants the access. | |
119 | A sandboxed thread can only access a file path | |
120 | if all its enforced policy layers grant the access | |
121 | as well as all the other system access controls | |
122 | (e.g., filesystem DAC, other LSM policies, etc.). | |
123 | .\" | |
124 | .SS Bind mounts and OverlayFS | |
125 | Landlock enables restricting access to file hierarchies, | |
126 | which means that these access rights can be propagated with bind mounts | |
127 | (cf. | |
128 | .BR mount_namespaces (7)) | |
129 | but not with OverlayFS. | |
130 | .PP | |
131 | A bind mount mirrors a source file hierarchy to a destination. | |
132 | The destination hierarchy is then composed of the exact same files, | |
133 | on which Landlock rules can be tied, | |
134 | either via the source or the destination path. | |
135 | These rules restrict access when they are encountered on a path, | |
136 | which means that they can restrict access to | |
137 | multiple file hierarchies at the same time, | |
138 | whether these hierarchies are the result of bind mounts or not. | |
139 | .PP | |
140 | An OverlayFS mount point consists of upper and lower layers. | |
141 | These layers are combined in a merge directory, result of the mount point. | |
142 | This merge hierarchy may include files from the upper and lower layers, | |
143 | but modifications performed on the merge hierarchy | |
144 | only reflect on the upper layer. | |
145 | From a Landlock policy point of view, | |
146 | each of the OverlayFS layers and merge hierarchies is standalone and | |
147 | contains its own set of files and directories, | |
148 | which is different from a bind mount. | |
085a9296 AC |
149 | A policy restricting an OverlayFS layer will not restrict |
150 | the resulted merged hierarchy, and vice versa. | |
38454e3f MS |
151 | Landlock users should then only think about file hierarchies they want to |
152 | allow access to, regardless of the underlying filesystem. | |
153 | .\" | |
154 | .SS Inheritance | |
155 | Every new thread resulting from a | |
156 | .BR clone (2) | |
157 | inherits Landlock domain restrictions from its parent. | |
158 | This is similar to the | |
159 | .BR seccomp (2) | |
160 | inheritance or any other LSM dealing with tasks' | |
161 | .BR credentials (7). | |
162 | For instance, one process's thread may apply Landlock rules to itself, | |
163 | but they will not be automatically applied to other sibling threads | |
164 | (unlike POSIX thread credential changes, cf. | |
165 | .BR nptl (7)). | |
166 | .PP | |
167 | When a thread sandboxes itself, | |
168 | we have the guarantee that the related security policy | |
169 | will stay enforced on all this thread's descendants. | |
170 | This allows creating standalone and modular security policies | |
171 | per application, | |
172 | which will automatically be composed between themselves | |
173 | according to their runtime parent policies. | |
174 | .\" | |
175 | .SS Ptrace restrictions | |
176 | A sandboxed process has less privileges than a non-sandboxed process and | |
177 | must then be subject to additional restrictions | |
178 | when manipulating another process. | |
179 | To be allowed to use | |
180 | .BR ptrace (2) | |
181 | and related syscalls on a target process, | |
182 | a sandboxed process should have a subset of the target process rules, | |
183 | which means the tracee must be in a sub-domain of the tracer. | |
184 | .SH VERSIONS | |
185 | Landlock was added in Linux 5.13. | |
186 | .SH NOTES | |
187 | Landlock is enabled by | |
188 | .BR CONFIG_SECURITY_LANDLOCK . | |
189 | The | |
190 | .I lsm=lsm1,...,lsmN | |
191 | command line parameter controls the sequence of the initialization of | |
192 | Linux Security Modules. | |
193 | It must contain the string | |
194 | .I landlock | |
195 | to enable Landlock. | |
196 | If the command line parameter is not specified, | |
197 | the initialization falls back to the value of the deprecated | |
198 | .I security= | |
199 | command line parameter and further to the value of CONFIG_LSM. | |
200 | We can check that Landlock is enabled by looking for | |
201 | .I landlock: Up and running. | |
202 | in kernel logs. | |
203 | .PP | |
204 | It is currently not possible to restrict some file-related actions | |
205 | accessible through these system call families: | |
206 | .BR chdir (2), | |
207 | .BR truncate (2), | |
208 | .BR stat (2), | |
209 | .BR flock (2), | |
210 | .BR chmod (2), | |
211 | .BR chown (2), | |
212 | .BR setxattr (2), | |
213 | .BR utime (2), | |
214 | .BR ioctl (2), | |
215 | .BR fcntl (2), | |
216 | .BR access (2). | |
217 | Future Landlock evolutions will enable to restrict them. | |
218 | .SH EXAMPLES | |
219 | We first need to create the ruleset that will contain our rules. | |
220 | For this example, | |
221 | the ruleset will contain rules that only allow read actions, | |
222 | but write actions will be denied. | |
223 | The ruleset then needs to handle both of these kind of actions. | |
224 | See below for the description of filesystem actions. | |
225 | .PP | |
226 | .in +4n | |
227 | .EX | |
085a9296 | 228 | struct landlock_ruleset_attr ruleset_attr = {0}; |
38454e3f | 229 | int ruleset_fd; |
085a9296 AC |
230 | |
231 | ruleset_attr.handled_access_fs = | |
38454e3f MS |
232 | LANDLOCK_ACCESS_FS_EXECUTE | |
233 | LANDLOCK_ACCESS_FS_WRITE_FILE | | |
234 | LANDLOCK_ACCESS_FS_READ_FILE | | |
235 | LANDLOCK_ACCESS_FS_READ_DIR | | |
236 | LANDLOCK_ACCESS_FS_REMOVE_DIR | | |
237 | LANDLOCK_ACCESS_FS_REMOVE_FILE | | |
238 | LANDLOCK_ACCESS_FS_MAKE_CHAR | | |
239 | LANDLOCK_ACCESS_FS_MAKE_DIR | | |
240 | LANDLOCK_ACCESS_FS_MAKE_REG | | |
241 | LANDLOCK_ACCESS_FS_MAKE_SOCK | | |
242 | LANDLOCK_ACCESS_FS_MAKE_FIFO | | |
243 | LANDLOCK_ACCESS_FS_MAKE_BLOCK | | |
085a9296 | 244 | LANDLOCK_ACCESS_FS_MAKE_SYM; |
38454e3f MS |
245 | |
246 | ruleset_fd = landlock_create_ruleset(&ruleset_attr, sizeof(ruleset_attr), 0); | |
085a9296 | 247 | if (ruleset_fd == -1) { |
38454e3f | 248 | perror("Failed to create a ruleset"); |
085a9296 | 249 | exit(EXIT_FAILURE); |
38454e3f MS |
250 | } |
251 | .EE | |
252 | .in | |
253 | .PP | |
254 | We can now add a new rule to this ruleset thanks to the returned file | |
255 | descriptor referring to this ruleset. | |
256 | The rule will only allow reading the file hierarchy | |
257 | .IR /usr . | |
258 | Without another rule, write actions would then be denied by the ruleset. | |
259 | To add | |
260 | .I /usr | |
261 | to the ruleset, we open it with the | |
262 | .I O_PATH | |
263 | flag and fill the | |
264 | .I struct landlock_path_beneath_attr | |
265 | with this file descriptor. | |
266 | .PP | |
267 | .in +4n | |
268 | .EX | |
085a9296 | 269 | struct landlock_path_beneath_attr path_beneath = {0}; |
38454e3f | 270 | int err; |
085a9296 AC |
271 | |
272 | path_beneath.allowed_access = | |
38454e3f MS |
273 | LANDLOCK_ACCESS_FS_EXECUTE | |
274 | LANDLOCK_ACCESS_FS_READ_FILE | | |
085a9296 | 275 | LANDLOCK_ACCESS_FS_READ_DIR; |
38454e3f MS |
276 | |
277 | path_beneath.parent_fd = open("/usr", O_PATH | O_CLOEXEC); | |
085a9296 | 278 | if (path_beneath.parent_fd == -1) { |
38454e3f MS |
279 | perror("Failed to open file"); |
280 | close(ruleset_fd); | |
085a9296 | 281 | exit(EXIT_FAILURE); |
38454e3f MS |
282 | } |
283 | err = landlock_add_rule(ruleset_fd, LANDLOCK_RULE_PATH_BENEATH, | |
284 | &path_beneath, 0); | |
285 | close(path_beneath.parent_fd); | |
286 | if (err) { | |
287 | perror("Failed to update ruleset"); | |
288 | close(ruleset_fd); | |
085a9296 | 289 | exit(EXIT_FAILURE); |
38454e3f MS |
290 | } |
291 | .EE | |
292 | .in | |
293 | .PP | |
294 | We now have a ruleset with one rule allowing read access to | |
295 | .I /usr | |
296 | while denying all other handled accesses for the filesystem. | |
297 | The next step is to restrict the current thread from gaining more | |
298 | privileges | |
299 | (e.g., thanks to a set-user-ID binary). | |
300 | .PP | |
301 | .in +4n | |
302 | .EX | |
303 | if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) { | |
304 | perror("Failed to restrict privileges"); | |
305 | close(ruleset_fd); | |
085a9296 | 306 | exit(EXIT_FAILURE); |
38454e3f MS |
307 | } |
308 | .EE | |
309 | .in | |
310 | .PP | |
311 | The current thread is now ready to sandbox itself with the ruleset. | |
312 | .PP | |
313 | .in +4n | |
314 | .EX | |
315 | if (landlock_restrict_self(ruleset_fd, 0)) { | |
316 | perror("Failed to enforce ruleset"); | |
317 | close(ruleset_fd); | |
085a9296 | 318 | exit(EXIT_FAILURE); |
38454e3f MS |
319 | } |
320 | close(ruleset_fd); | |
321 | .EE | |
322 | .in | |
323 | .PP | |
324 | If the | |
325 | .BR landlock_restrict_self (2) | |
085a9296 AC |
326 | system call succeeds, the current thread is now restricted and |
327 | this policy will be enforced on all its subsequently created children as well. | |
38454e3f MS |
328 | Once a thread is landlocked, there is no way to remove its security policy; |
329 | only adding more restrictions is allowed. | |
330 | These threads are now in a new Landlock domain, | |
331 | merge of their parent one (if any) with the new ruleset. | |
332 | .PP | |
333 | Full working code can be found in | |
085a9296 | 334 | .UR https://git.kernel.org/\:pub/\:scm/\:linux/\:kernel/\:git/\:stable/\:linux.git/\:tree/\:samples/\:landlock/\:sandboxer.c |
38454e3f MS |
335 | .UE |
336 | .SH SEE ALSO | |
337 | .BR landlock_create_ruleset (2), | |
338 | .BR landlock_add_rule (2), | |
339 | .BR landlock_restrict_self (2) | |
340 | .PP | |
085a9296 | 341 | .UR https://landlock.io/ |
38454e3f | 342 | .UE |