Debian Codegraph @

upstream/debian-unstable/man2/seccomp_unotify.2

raw
1 .\" Copyright 2020, Michael Kerrisk <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH seccomp_unotify 2 2026-02-22 "Linux man-pages 6.18"
7 .SH NAME
8 seccomp_unotify \- Seccomp user-space notification mechanism
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ,\~ \-lc )
12 .SH SYNOPSIS
13 .nf
14 .B #include <linux/seccomp.h>
15 .B #include <linux/filter.h>
16 .B #include <linux/audit.h>
17 .P
18 .BI "int seccomp(unsigned int " operation ", unsigned int " flags \
19 ", void *" args );
20 .P
21 .B #include <sys/ioctl.h>
22 .P
23 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_RECV,"
24 .BI " struct seccomp_notif *" req );
25 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_SEND,"
26 .BI " struct seccomp_notif_resp *" resp );
27 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ID_VALID, __u64 *" id );
28 .BI "int ioctl(int " fd ", SECCOMP_IOCTL_NOTIF_ADDFD,"
29 .BI " struct seccomp_notif_addfd *" addfd );
30 .fi
31 .SH DESCRIPTION
32 This page describes the user-space notification mechanism provided by the
33 Secure Computing (seccomp) facility.
34 As well as the use of the
35 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
36 flag, the
37 .B SECCOMP_RET_USER_NOTIF
38 action value, and the
39 .B SECCOMP_GET_NOTIF_SIZES
40 operation described in
41 .BR seccomp (2),
42 this mechanism involves the use of a number of related
43 .BR ioctl (2)
44 operations (described below).
45 .\"
46 .SS Overview
47 In conventional usage of a seccomp filter,
48 the decision about how to treat a system call is made by the filter itself.
49 By contrast, the user-space notification mechanism allows
50 the seccomp filter to delegate
51 the handling of the system call to another user-space process.
52 Note that this mechanism is explicitly
53 .B not
54 intended as a method implementing security policy;
55 see NOTES.
56 .P
57 In the discussion that follows,
58 the thread(s) on which the seccomp filter is installed is (are)
59 referred to as the
60 .IR target ,
61 and the process that is notified by the user-space notification
62 mechanism is referred to as the
63 .IR supervisor .
64 .P
65 A suitably privileged supervisor can use the user-space notification
66 mechanism to perform actions on behalf of the target.
67 The advantage of the user-space notification mechanism is that
68 the supervisor will
69 usually be able to retrieve information about the target and the
70 performed system call that the seccomp filter itself cannot.
71 (A seccomp filter is limited in the information it can obtain and
72 the actions that it can perform because it
73 is running on a virtual machine inside the kernel.)
74 .P
75 An overview of the steps performed by the target and the supervisor
76 is as follows:
77 .\"-------------------------------------
78 .IP (1) 5
79 The target establishes a seccomp filter in the usual manner,
80 but with two differences:
81 .RS
82 .IP \[bu] 3
83 The
84 .BR seccomp (2)
85 .I flags
86 argument includes the flag
87 .BR SECCOMP_FILTER_FLAG_NEW_LISTENER .
88 Consequently, the return value of the (successful)
89 .BR seccomp (2)
90 call is a new "listening"
91 file descriptor that can be used to receive notifications.
92 Only one "listening" seccomp filter can be installed for a thread.
93 .\" FIXME
94 .\" Is the last sentence above correct?
95 .\"
96 .\" Kees Cook (25 Oct 2020) notes:
97 .\"
98 .\" I like this limitation, but I expect that it'll need to change in the
99 .\" future. Even with LSMs, we see the need for arbitrary stacking, and the
100 .\" idea of there being only 1 supervisor will eventually break down. Right
101 .\" now there is only 1 because only container managers are using this
102 .\" feature. But if some daemon starts using it to isolate some thread,
103 .\" suddenly it might break if a container manager is trying to listen to it
104 .\" too, etc. I expect it won't be needed soon, but I do think it'll change.
105 .\"
106 .IP \[bu]
107 In cases where it is appropriate, the seccomp filter returns the action value
108 .BR SECCOMP_RET_USER_NOTIF .
109 This return value will trigger a notification event.
110 .RE
111 .\"-------------------------------------
112 .IP (2)
113 In order that the supervisor can obtain notifications
114 using the listening file descriptor,
115 (a duplicate of) that file descriptor must be passed from
116 the target to the supervisor.
117 One way in which this could be done is by passing the file descriptor
118 over a UNIX domain socket connection between the target and the supervisor
119 (using the
120 .B SCM_RIGHTS
121 ancillary message type described in
122 .BR unix (7)).
123 Another way to do this is through the use of
124 .BR pidfd_getfd (2).
125 .\" Jann Horn:
126 .\" Instead of using unix domain sockets to send the fd to the
127 .\" parent, I think you could also use clone3() with
128 .\" flags==CLONE_FILES|SIGCHLD, dup2() the seccomp fd to an fd
129 .\" that was reserved in the parent, call unshare(CLONE_FILES)
130 .\" in the child after setting up the seccomp fd, and wake
131 .\" up the parent with something like pthread_cond_signal()?
132 .\" I'm not sure whether that'd look better or worse in the
133 .\" end though, so maybe just ignore this comment.
134 .\"-------------------------------------
135 .IP (3)
136 The supervisor will receive notification events
137 on the listening file descriptor.
138 These events are returned as structures of type
139 .IR seccomp_notif .
140 Because this structure and its size may evolve over kernel versions,
141 the supervisor must first determine the size of this structure
142 using the
143 .BR seccomp (2)
144 .B SECCOMP_GET_NOTIF_SIZES
145 operation, which returns a structure of type
146 .IR seccomp_notif_sizes .
147 The supervisor allocates a buffer of size
148 .I seccomp_notif_sizes.seccomp_notif
149 bytes to receive notification events.
150 In addition,the supervisor allocates another buffer of size
151 .I seccomp_notif_sizes.seccomp_notif_resp
152 bytes for the response (a
153 .I struct seccomp_notif_resp
154 structure)
155 that it will provide to the kernel (and thus the target).
156 .\"-------------------------------------
157 .IP (4)
158 The target then performs its workload,
159 which includes system calls that will be controlled by the seccomp filter.
160 Whenever one of these system calls causes the filter to return the
161 .B SECCOMP_RET_USER_NOTIF
162 action value, the kernel does
163 .I not
164 (yet) execute the system call;
165 instead, execution of the target is temporarily blocked inside
166 the kernel (in a sleep state that is interruptible by signals)
167 and a notification event is generated on the listening file descriptor.
168 .\"-------------------------------------
169 .IP (5)
170 The supervisor can now repeatedly monitor the
171 listening file descriptor for
172 .BR SECCOMP_RET_USER_NOTIF -triggered
173 events.
174 To do this, the supervisor uses the
175 .B SECCOMP_IOCTL_NOTIF_RECV
176 .BR ioctl (2)
177 operation to read information about a notification event;
178 this operation blocks until an event is available.
179 The operation returns a
180 .I seccomp_notif
181 structure containing information about the system call
182 that is being attempted by the target.
183 (As described in NOTES,
184 the file descriptor can also be monitored with
185 .BR select (2),
186 .BR poll (2),
187 or
188 .BR epoll (7).)
189 .\" FIXME
190 .\" Christian Brauner:
191 .\"
192 .\" Do we support O_NONBLOCK with SECCOMP_IOCTL_NOTIF_RECV and if
193 .\" not should we?
194 .\"
195 .\" Michael Kerrisk:
196 .\"
197 .\" A quick test suggests that O_NONBLOCK has no effect on the blocking
198 .\" behavior of SECCOMP_IOCTL_NOTIF_RECV.
199 .
200 .\"-------------------------------------
201 .IP (6)
202 The
203 .I seccomp_notif
204 structure returned by the
205 .B SECCOMP_IOCTL_NOTIF_RECV
206 operation includes the same information (a
207 .I seccomp_data
208 structure) that was passed to the seccomp filter.
209 This information allows the supervisor to discover the system call number and
210 the arguments for the target's system call.
211 In addition, the notification event contains the ID of the thread
212 that triggered the notification and a unique cookie value that
213 is used in subsequent
214 .B SECCOMP_IOCTL_NOTIF_ID_VALID
215 and
216 .B SECCOMP_IOCTL_NOTIF_SEND
217 operations.
218 .IP
219 The information in the notification can be used to discover the
220 values of pointer arguments for the target's system call.
221 (This is something that can't be done from within a seccomp filter.)
222 One way in which the supervisor can do this is to open the corresponding
223 .IR /proc/ tid /mem
224 file (see
225 .BR proc (5))
226 and read bytes from the location that corresponds to one of
227 the pointer arguments whose value is supplied in the notification event.
228 .\" Tycho Andersen mentioned that there are alternatives to /proc/PID/mem,
229 .\" such as ptrace() and /proc/PID/map_files
230 (The supervisor must be careful to avoid
231 a race condition that can occur when doing this;
232 see the description of the
233 .B SECCOMP_IOCTL_NOTIF_ID_VALID
234 .BR ioctl (2)
235 operation below.)
236 In addition,
237 the supervisor can access other system information that is visible
238 in user space but which is not accessible from a seccomp filter.
239 .\"-------------------------------------
240 .IP (7)
241 Having obtained information as per the previous step,
242 the supervisor may then choose to perform an action in response
243 to the target's system call
244 (which, as noted above, is not executed when the seccomp filter returns the
245 .B SECCOMP_RET_USER_NOTIF
246 action value).
247 .IP
248 One example use case here relates to containers.
249 The target may be located inside a container where
250 it does not have sufficient capabilities to mount a filesystem
251 in the container's mount namespace.
252 However, the supervisor may be a more privileged process that
253 does have sufficient capabilities to perform the mount operation.
254 .\"-------------------------------------
255 .IP (8)
256 The supervisor then sends a response to the notification.
257 The information in this response is used by the kernel to construct
258 a return value for the target's system call and provide
259 a value that will be assigned to the
260 .I errno
261 variable of the target.
262 .IP
263 The response is sent using the
264 .B SECCOMP_IOCTL_NOTIF_SEND
265 .BR ioctl (2)
266 operation, which is used to transmit a
267 .I seccomp_notif_resp
268 structure to the kernel.
269 This structure includes a cookie value that the supervisor obtained in the
270 .I seccomp_notif
271 structure returned by the
272 .B SECCOMP_IOCTL_NOTIF_RECV
273 operation.
274 This cookie value allows the kernel to associate the response with the
275 target.
276 This structure must include the cookie value that the supervisor
277 obtained in the
278 .I seccomp_notif
279 structure returned by the
280 .B SECCOMP_IOCTL_NOTIF_RECV
281 operation;
282 the cookie allows the kernel to associate the response with the target.
283 .\"-------------------------------------
284 .IP (9)
285 Once the notification has been sent,
286 the system call in the target thread unblocks,
287 returning the information that was provided by the supervisor
288 in the notification response.
289 .\"-------------------------------------
290 .P
291 As a variation on the last two steps,
292 the supervisor can send a response that tells the kernel that
293 it should execute the target thread's system call;
294 see the discussion of
295 .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE ,
296 below.
297 .\"
298 .SH IOCTL OPERATIONS
299 The following
300 .BR ioctl (2)
301 operations are supported by the seccomp user-space
302 notification file descriptor.
303 For each of these operations, the first (file descriptor) argument of
304 .BR ioctl (2)
305 is the listening file descriptor returned by a call to
306 .BR seccomp (2)
307 with the
308 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
309 flag.
310 .\"
311 .SS SECCOMP_IOCTL_NOTIF_RECV
312 The
313 .B SECCOMP_IOCTL_NOTIF_RECV
314 operation (available since Linux 5.0) is used to obtain a user-space
315 notification event.
316 If no such event is currently pending,
317 the operation blocks until an event occurs.
318 The third
319 .BR ioctl (2)
320 argument is a pointer to a structure of the following form
321 which contains information about the event.
322 This structure must be zeroed out before the call.
323 .P
324 .in +4n
325 .EX
326 struct seccomp_notif {
327 __u64 id; /* Cookie */
328 __u32 pid; /* TID of target thread */
329 __u32 flags; /* Currently unused (0) */
330 struct seccomp_data data; /* See seccomp(2) */
331 };
332 .EE
333 .in
334 .P
335 The fields in this structure are as follows:
336 .TP
337 .I id
338 This is a cookie for the notification.
339 Each such cookie is guaranteed to be unique for the corresponding
340 seccomp filter.
341 .RS
342 .IP \[bu] 3
343 The cookie can be used with the
344 .B SECCOMP_IOCTL_NOTIF_ID_VALID
345 .BR ioctl (2)
346 operation described below.
347 .IP \[bu]
348 When returning a notification response to the kernel,
349 the supervisor must include the cookie value in the
350 .I seccomp_notif_resp
351 structure that is specified as the argument of the
352 .B SECCOMP_IOCTL_NOTIF_SEND
353 operation.
354 .RE
355 .TP
356 .I pid
357 This is the thread ID of the target thread that triggered
358 the notification event.
359 .TP
360 .I flags
361 This is a bit mask of flags providing further information on the event.
362 In the current implementation, this field is always zero.
363 .TP
364 .I data
365 This is a
366 .I seccomp_data
367 structure containing information about the system call that
368 triggered the notification.
369 This is the same structure that is passed to the seccomp filter.
370 See
371 .BR seccomp (2)
372 for details of this structure.
373 .P
374 On success,
375 this operation returns 0;
376 on failure, \-1 is returned, and
377 .I errno
378 is set to indicate the error.
379 This operation can fail with the following errors:
380 .TP
381 .BR EINVAL " (since Linux 5.5)"
382 .\" commit 2882d53c9c6f3b8311d225062522f03772cf0179
383 The
384 .I seccomp_notif
385 structure that was passed to the call contained nonzero fields.
386 .TP
387 .B ENOENT
388 The target thread was killed by a signal as the notification information
389 was being generated,
390 or the target's (blocked) system call was interrupted by a signal handler.
391 .\" FIXME
392 .\" From my experiments,
393 .\" it appears that if a SECCOMP_IOCTL_NOTIF_RECV is done after
394 .\" the target thread terminates, then the ioctl() simply
395 .\" blocks (rather than returning an error to indicate that the
396 .\" target no longer exists).
397 .\"
398 .\" I found that surprising, and it required some contortions in
399 .\" the example program. It was not possible to code my SIGCHLD
400 .\" handler (which reaps the zombie when the worker/target
401 .\" terminates) to simply set a flag checked in the main
402 .\" handleNotifications() loop, since this created an
403 .\" unavoidable race where the child might terminate just after
404 .\" I had checked the flag, but before I blocked (forever!) in the
405 .\" SECCOMP_IOCTL_NOTIF_RECV operation. Instead, I had to code
406 .\" the signal handler to simply call _exit(2) in order to
407 .\" terminate the parent process (the supervisor).
408 .\"
409 .\" Is this expected behavior? It seems to me rather
410 .\" desirable that SECCOMP_IOCTL_NOTIF_RECV should give an error
411 .\" if the target has terminated.
412 .\"
413 .\" Jann posted a patch to rectify this, but there was no response
414 .\" (Lore link: https://bit.ly/3jvUBxk) to his question about fixing
415 .\" this issue. (I've tried building with the patch, but encountered
416 .\" an issue with the target process entering D state after a signal.)
417 .\"
418 .\" For now, this behavior is documented in BUGS.
419 .\"
420 .\" Kees Cook commented: Let's change [this] ASAP!
421 .\"
422 .SS SECCOMP_IOCTL_NOTIF_ID_VALID
423 The
424 .B SECCOMP_IOCTL_NOTIF_ID_VALID
425 operation (available since Linux 5.0) is used to check that a notification ID
426 returned by an earlier
427 .B SECCOMP_IOCTL_NOTIF_RECV
428 operation is still valid
429 (i.e., that the target still exists and its system call
430 is still blocked waiting for a response).
431 .P
432 The third
433 .BR ioctl (2)
434 argument is a pointer to the cookie
435 .RI ( id )
436 returned by the
437 .B SECCOMP_IOCTL_NOTIF_RECV
438 operation.
439 .P
440 This operation is necessary to avoid race conditions that can occur when the
441 .I pid
442 returned by the
443 .B SECCOMP_IOCTL_NOTIF_RECV
444 operation terminates, and that process ID is reused by another process.
445 An example of this kind of race is the following
446 .IP (1) 5
447 A notification is generated on the listening file descriptor.
448 The returned
449 .I seccomp_notif
450 contains the TID of the target thread (in the
451 .I pid
452 field of the structure).
453 .IP (2)
454 The target terminates.
455 .IP (3)
456 Another thread or process is created on the system that by chance reuses the
457 TID that was freed when the target terminated.
458 .IP (4)
459 The supervisor
460 .BR open (2)s
461 the
462 .IR /proc/ tid /mem
463 file for the TID obtained in step 1, with the intention of (say)
464 inspecting the memory location(s) that containing the argument(s) of
465 the system call that triggered the notification in step 1.
466 .P
467 In the above scenario, the risk is that the supervisor may try
468 to access the memory of a process other than the target.
469 This race can be avoided by following the call to
470 .BR open (2)
471 with a
472 .B SECCOMP_IOCTL_NOTIF_ID_VALID
473 operation to verify that the process that generated the notification
474 is still alive.
475 (Note that if the target terminates after the latter step,
476 a subsequent
477 .BR read (2)
478 from the file descriptor may return 0, indicating end of file.)
479 .\" Jann Horn:
480 .\" the PID can be reused, but the /proc/$pid directory is
481 .\" internally not associated with the numeric PID, but,
482 .\" conceptually speaking, with a specific incarnation of the
483 .\" PID, or something like that. (Actually, it is associated
484 .\" with the "struct pid", which is not reused, instead of the
485 .\" numeric PID.
486 .P
487 See NOTES for a discussion of other cases where
488 .B SECCOMP_IOCTL_NOTIF_ID_VALID
489 checks must be performed.
490 .P
491 On success (i.e., the notification ID is still valid),
492 this operation returns 0.
493 On failure (i.e., the notification ID is no longer valid),
494 \-1 is returned, and
495 .I errno
496 is set to
497 .BR ENOENT .
498 .\"
499 .SS SECCOMP_IOCTL_NOTIF_SEND
500 The
501 .B SECCOMP_IOCTL_NOTIF_SEND
502 operation (available since Linux 5.0)
503 is used to send a notification response back to the kernel.
504 The third
505 .BR ioctl (2)
506 argument of this structure is a pointer to a structure of the following form:
507 .P
508 .in +4n
509 .EX
510 struct seccomp_notif_resp {
511 __u64 id; /* Cookie value */
512 __s64 val; /* Success return value */
513 __s32 error; /* 0 (success) or negative error number */
514 __u32 flags; /* See below */
515 };
516 .EE
517 .in
518 .P
519 The fields of this structure are as follows:
520 .TP
521 .I id
522 This is the cookie value that was obtained using the
523 .B SECCOMP_IOCTL_NOTIF_RECV
524 operation.
525 This cookie value allows the kernel to correctly associate this response
526 with the system call that triggered the user-space notification.
527 .TP
528 .I val
529 This is the value that will be used for
530 a spoofed success return for the target's system call;
531 see below.
532 .TP
533 .I error
534 This is the value that will be used as the error number
535 .RI ( errno )
536 for a spoofed error return for the target's system call;
537 see below.
538 .TP
539 .I flags
540 This is a bit mask that includes zero or more of the following flags:
541 .RS
542 .TP
543 .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE " (since Linux 5.5)"
544 Tell the kernel to execute the target's system call.
545 .\" commit fb3c5386b382d4097476ce9647260fc89b34afdb
546 .RE
547 .P
548 Two kinds of response are possible:
549 .IP \[bu] 3
550 A response to the kernel telling it to execute the
551 target's system call.
552 In this case, the
553 .I flags
554 field includes
555 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
556 and the
557 .I error
558 and
559 .I val
560 fields must be zero.
561 .IP
562 This kind of response can be useful in cases where the supervisor needs
563 to do deeper analysis of the target's system call than is possible
564 from a seccomp filter (e.g., examining the values of pointer arguments),
565 and, having decided that the system call does not require emulation
566 by the supervisor, the supervisor wants the system call to
567 be executed normally in the target.
568 .IP
569 The
570 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
571 flag should be used with caution;
572 see NOTES.
573 .IP \[bu]
574 A spoofed return value for the target's system call.
575 In this case, the kernel does not execute the target's system call,
576 instead causing the system call to return a spoofed value as specified by
577 fields of the
578 .I seccomp_notif_resp
579 structure.
580 The supervisor should set the fields of this structure as follows:
581 .RS
582 .IP \[bu] 3
583 .I flags
584 does not contain
585 .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE .
586 .IP \[bu]
587 .I error
588 is set either to 0 for a spoofed "success" return or to a negative
589 error number for a spoofed "failure" return.
590 In the former case, the kernel causes the target's system call
591 to return the value specified in the
592 .I val
593 field.
594 In the latter case, the kernel causes the target's system call
595 to return \-1, and
596 .I errno
597 is assigned the negated
598 .I error
599 value.
600 .IP \[bu]
601 .I val
602 is set to a value that will be used as the return value for a spoofed
603 "success" return for the target's system call.
604 The value in this field is ignored if the
605 .I error
606 field contains a nonzero value.
607 .\" FIXME
608 .\" Kees Cook suggested:
609 .\"
610 .\" Strictly speaking, this is architecture specific, but
611 .\" all architectures do it this way. Should seccomp enforce
612 .\" val == 0 when err != 0 ?
613 .\"
614 .\" Christian Brauner
615 .\"
616 .\" Feels like it should, at least for the SEND ioctl where we already
617 .\" verify that val and err are both 0 when CONTINUE is specified (as you
618 .\" pointed out correctly above).
619 .RE
620 .P
621 On success,
622 this operation returns 0;
623 on failure, \-1 is returned, and
624 .I errno
625 is set to indicate the error.
626 This operation can fail with the following errors:
627 .TP
628 .B EINPROGRESS
629 A response to this notification has already been sent.
630 .TP
631 .B EINVAL
632 An invalid value was specified in the
633 .I flags field.
634 .TP
635 .B
636 .B EINVAL
637 The
638 .I flags
639 field contained
640 .BR SECCOMP_USER_NOTIF_FLAG_CONTINUE ,
641 and the
642 .I error
643 or
644 .I val
645 field was not zero.
646 .TP
647 .B ENOENT
648 The blocked system call in the target
649 has been interrupted by a signal handler
650 or the target has terminated.
651 .\" Jann Horn notes:
652 .\" you could also get this [ENOENT] if a response has already
653 .\" been sent, instead of EINPROGRESS - the only difference is
654 .\" whether the target thread has picked up the response yet
655 .\"
656 .SS SECCOMP_IOCTL_NOTIF_ADDFD
657 The
658 .B SECCOMP_IOCTL_NOTIF_ADDFD
659 operation (available since Linux 5.9)
660 allows the supervisor to install a file descriptor
661 into the target's file descriptor table.
662 Much like the use of
663 .B SCM_RIGHTS
664 messages described in
665 .BR unix (7),
666 this operation is semantically equivalent to duplicating
667 a file descriptor from the supervisor's file descriptor table
668 into the target's file descriptor table.
669 .P
670 The
671 .B SECCOMP_IOCTL_NOTIF_ADDFD
672 operation permits the supervisor to emulate a target system call (such as
673 .BR socket (2)
674 or
675 .BR openat (2))
676 that generates a file descriptor.
677 The supervisor can perform the system call that generates
678 the file descriptor (and associated open file description)
679 and then use this operation to allocate
680 a file descriptor that refers to the same open file description in the target.
681 (For an explanation of open file descriptions, see
682 .BR open (2).)
683 .P
684 Once this operation has been performed,
685 the supervisor can close its copy of the file descriptor.
686 .P
687 In the target,
688 the received file descriptor is subject to the same
689 Linux Security Module (LSM) checks as are applied to a file descriptor
690 that is received in an
691 .B SCM_RIGHTS
692 ancillary message.
693 If the file descriptor refers to a socket,
694 it inherits the cgroup version 1 network controller settings
695 .RI ( classid
696 and
697 .IR netprioidx )
698 of the target.
699 .P
700 The third
701 .BR ioctl (2)
702 argument is a pointer to a structure of the following form:
703 .P
704 .in +4n
705 .EX
706 struct seccomp_notif_addfd {
707 __u64 id; /* Cookie value */
708 __u32 flags; /* Flags */
709 __u32 srcfd; /* Local file descriptor number */
710 __u32 newfd; /* 0 or desired file descriptor
711 number in target */
712 __u32 newfd_flags; /* Flags to set on target file
713 descriptor */
714 };
715 .EE
716 .in
717 .P
718 The fields in this structure are as follows:
719 .TP
720 .I id
721 This field should be set to the notification ID
722 (cookie value) that was obtained via
723 .BR SECCOMP_IOCTL_NOTIF_RECV .
724 .TP
725 .I flags
726 This field is a bit mask of flags that modify the behavior of the operation.
727 Currently, only one flag is supported:
728 .RS
729 .TP
730 .B SECCOMP_ADDFD_FLAG_SETFD
731 When allocating the file descriptor in the target,
732 use the file descriptor number specified in the
733 .I newfd
734 field.
735 .TP
736 .BR SECCOMP_ADDFD_FLAG_SEND " (since Linux 5.14)"
737 .\" commit 0ae71c7720e3ae3aabd2e8a072d27f7bd173d25c
738 Perform the equivalent of
739 .B SECCOMP_IOCTL_NOTIF_ADDFD
740 plus
741 .B SECCOMP_IOCTL_NOTIF_SEND
742 as an atomic operation.
743 On successful invocation, the target process's
744 .I errno
745 will be 0
746 and the return value will be the file descriptor number
747 that was allocated in the target.
748 If allocating the file descriptor in the target fails,
749 the target's system call continues to be blocked
750 until a successful response is sent.
751 .RE
752 .TP
753 .I srcfd
754 This field should be set to the number of the file descriptor
755 in the supervisor that is to be duplicated.
756 .TP
757 .I newfd
758 This field determines which file descriptor number is allocated in the target.
759 If the
760 .B SECCOMP_ADDFD_FLAG_SETFD
761 flag is set,
762 then this field specifies which file descriptor number should be allocated.
763 If this file descriptor number is already open in the target,
764 it is atomically closed and reused.
765 If the descriptor duplication fails due to an LSM check, or if
766 .I srcfd
767 is not a valid file descriptor,
768 the file descriptor
769 .I newfd
770 will not be closed in the target process.
771 .IP
772 If the
773 .B SECCOMP_ADDFD_FLAG_SETFD
774 flag it not set, then this field must be 0,
775 and the kernel allocates the lowest unused file descriptor number
776 in the target.
777 .TP
778 .I newfd_flags
779 This field is a bit mask specifying flags that should be set on
780 the file descriptor that is received in the target process.
781 Currently, only the following flag is implemented:
782 .RS
783 .TP
784 .B O_CLOEXEC
785 Set the close-on-exec flag on the received file descriptor.
786 .RE
787 .P
788 On success, this
789 .BR ioctl (2)
790 call returns the number of the file descriptor that was allocated
791 in the target.
792 Assuming that the emulated system call is one that returns
793 a file descriptor as its function result (e.g.,
794 .BR socket (2)),
795 this value can be used as the return value
796 .RI ( resp.val )
797 that is supplied in the response that is subsequently sent with the
798 .B SECCOMP_IOCTL_NOTIF_SEND
799 operation.
800 .P
801 On error, \-1 is returned and
802 .I errno
803 is set to indicate the error.
804 .P
805 This operation can fail with the following errors:
806 .TP
807 .B EBADF
808 Allocating the file descriptor in the target would cause the target's
809 .B RLIMIT_NOFILE
810 limit to be exceeded (see
811 .BR getrlimit (2)).
812 .TP
813 .B EBUSY
814 If the flag
815 .B SECCOMP_IOCTL_NOTIF_SEND
816 is used, this means the operation can't proceed until other
817 .B SECCOMP_IOCTL_NOTIF_ADDFD
818 requests are processed.
819 .TP
820 .B EINPROGRESS
821 The user-space notification specified in the
822 .I id
823 field exists but has not yet been fetched (by a
824 .BR SECCOMP_IOCTL_NOTIF_RECV )
825 or has already been responded to (by a
826 .BR SECCOMP_IOCTL_NOTIF_SEND ).
827 .TP
828 .B EINVAL
829 An invalid flag was specified in the
830 .I flags
831 or
832 .I newfd_flags
833 field, or the
834 .I newfd
835 field is nonzero and the
836 .B SECCOMP_ADDFD_FLAG_SETFD
837 flag was not specified in the
838 .I flags
839 field.
840 .TP
841 .B EMFILE
842 The file descriptor number specified in
843 .I newfd
844 exceeds the limit specified in
845 .IR /proc/sys/fs/nr_open .
846 .TP
847 .B ENOENT
848 The blocked system call in the target
849 has been interrupted by a signal handler
850 or the target has terminated.
851 .P
852 Here is some sample code (with error handling omitted) that uses the
853 .B SECCOMP_ADDFD_FLAG_SETFD
854 operation (here, to emulate a call to
855 .BR openat (2)):
856 .P
857 .EX
858 .in +4n
859 int fd, removeFd;
860 \&
861 fd = openat(req\->data.args[0], path, req\->data.args[2],
862 req\->data.args[3]);
863 \&
864 struct seccomp_notif_addfd addfd;
865 addfd.id = req\->id; /* Cookie from SECCOMP_IOCTL_NOTIF_RECV */
866 addfd.srcfd = fd;
867 addfd.newfd = 0;
868 addfd.flags = 0;
869 addfd.newfd_flags = O_CLOEXEC;
870 \&
871 targetFd = ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ADDFD, &addfd);
872 \&
873 close(fd); /* No longer needed in supervisor */
874 \&
875 struct seccomp_notif_resp *resp;
876 /* Code to allocate 'resp' omitted */
877 resp\->id = req\->id;
878 resp\->error = 0; /* "Success" */
879 resp\->val = targetFd;
880 resp\->flags = 0;
881 ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp);
882 .in
883 .EE
884 .SH NOTES
885 One example use case for the user-space notification
886 mechanism is to allow a container manager
887 (a process which is typically running with more privilege than
888 the processes inside the container)
889 to mount block devices or create device nodes for the container.
890 The mount use case provides an example of where the
891 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
892 .BR ioctl (2)
893 operation is useful.
894 Upon receiving a notification for the
895 .BR mount (2)
896 system call, the container manager (the "supervisor") can distinguish
897 a request to mount a block filesystem
898 (which would not be possible for a "target" process inside the container)
899 and mount that file system.
900 If, on the other hand, the container manager detects that the operation
901 could be performed by the process inside the container
902 (e.g., a mount of a
903 .BR tmpfs (5)
904 filesystem), it can notify the kernel that the target process's
905 .BR mount (2)
906 system call can continue.
907 .\"
908 .SS select()/poll()/epoll semantics
909 The file descriptor returned when
910 .BR seccomp (2)
911 is employed with the
912 .B SECCOMP_FILTER_FLAG_NEW_LISTENER
913 flag can be monitored using
914 .BR poll (2),
915 .BR epoll (7),
916 and
917 .BR select (2).
918 These interfaces indicate that the file descriptor is ready as follows:
919 .IP \[bu] 3
920 When a notification is pending,
921 these interfaces indicate that the file descriptor is readable.
922 Following such an indication, a subsequent
923 .B SECCOMP_IOCTL_NOTIF_RECV
924 .BR ioctl (2)
925 will not block, returning either information about a notification
926 or else failing with the error
927 .B EINTR
928 if the target has been killed by a signal or its system call
929 has been interrupted by a signal handler.
930 .IP \[bu]
931 After the notification has been received (i.e., by the
932 .B SECCOMP_IOCTL_NOTIF_RECV
933 .BR ioctl (2)
934 operation), these interfaces indicate that the file descriptor is writable,
935 meaning that a notification response can be sent using the
936 .B SECCOMP_IOCTL_NOTIF_SEND
937 .BR ioctl (2)
938 operation.
939 .IP \[bu]
940 After the last thread using the filter has terminated and been reaped using
941 .BR waitpid (2)
942 (or similar),
943 the file descriptor indicates an end-of-file condition (readable in
944 .BR select (2);
945 .BR POLLHUP / EPOLLHUP
946 in
947 .BR poll (2)/
948 .BR epoll_wait (2)).
949 .SS Design goals; use of SECCOMP_USER_NOTIF_FLAG_CONTINUE
950 The intent of the user-space notification feature is
951 to allow system calls to be performed on behalf of the target.
952 The target's system call should either be handled by the supervisor or
953 allowed to continue normally in the kernel (where standard security
954 policies will be applied).
955 .P
956 .BR "Note well" :
957 this mechanism must not be used to make security policy decisions
958 about the system call,
959 which would be inherently race-prone for reasons described next.
960 .P
961 The
962 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
963 flag must be used with caution.
964 If set by the supervisor, the target's system call will continue.
965 However, there is a time-of-check, time-of-use race here,
966 since an attacker could exploit the interval of time where the target is
967 blocked waiting on the "continue" response to do things such as
968 rewriting the system call arguments.
969 .P
970 Note furthermore that a user-space notifier can be bypassed if
971 the existing filters allow the use of
972 .BR seccomp (2)
973 or
974 .BR prctl (2)
975 to install a filter that returns an action value with a higher precedence than
976 .B SECCOMP_RET_USER_NOTIF
977 (see
978 .BR seccomp (2)).
979 .P
980 It should thus be absolutely clear that the
981 seccomp user-space notification mechanism
982 .B can not
983 be used to implement a security policy!
984 It should only ever be used in scenarios where a more privileged process
985 supervises the system calls of a lesser privileged target to
986 get around kernel-enforced security restrictions when
987 the supervisor deems this safe.
988 In other words,
989 in order to continue a system call, the supervisor should be sure that
990 another security mechanism or the kernel itself will sufficiently block
991 the system call if its arguments are rewritten to something unsafe.
992 .\"
993 .SS Caveats regarding the use of
994 .IR /proc/ tid /mem
995 The discussion above noted the need to use the
996 .B SECCOMP_IOCTL_NOTIF_ID_VALID
997 .BR ioctl (2)
998 when opening the
999 .IR /proc/ tid /mem
1000 file of the target
1001 to avoid the possibility of accessing the memory of the wrong process
1002 in the event that the target terminates and its ID
1003 is recycled by another (unrelated) thread.
1004 However, the use of this
1005 .BR ioctl (2)
1006 operation is also necessary in other situations,
1007 as explained in the following paragraphs.
1008 .P
1009 Consider the following scenario, where the supervisor
1010 tries to read the pathname argument of a target's blocked
1011 .BR mount (2)
1012 system call:
1013 .IP (1) 5
1014 From one of its functions
1015 .RI ( func() ),
1016 the target calls
1017 .BR mount (2),
1018 which triggers a user-space notification and causes the target to block.
1019 .IP (2)
1020 The supervisor receives the notification, opens
1021 .IR /proc/ tid /mem ,
1022 and (successfully) performs the
1023 .B SECCOMP_IOCTL_NOTIF_ID_VALID
1024 check.
1025 .IP (3)
1026 The target receives a signal, which causes the
1027 .BR mount (2)
1028 to abort.
1029 .IP (4)
1030 The signal handler executes in the target, and returns.
1031 .IP (5)
1032 Upon return from the handler, the execution of
1033 .I func()
1034 resumes, and it returns (and perhaps other functions are called,
1035 overwriting the memory that had been used for the stack frame of
1036 .IR func() ).
1037 .IP (6)
1038 Using the address provided in the notification information,
1039 the supervisor reads from the target's memory location that used to
1040 contain the pathname.
1041 .IP (7)
1042 The supervisor now calls
1043 .BR mount (2)
1044 with some arbitrary bytes obtained in the previous step.
1045 .P
1046 The conclusion from the above scenario is this:
1047 since the target's blocked system call may be interrupted by a signal handler,
1048 the supervisor must be written to expect that the
1049 target may abandon its system call at
1050 .B any
1051 time;
1052 in such an event, any information that the supervisor obtained from
1053 the target's memory must be considered invalid.
1054 .P
1055 To prevent such scenarios,
1056 every read from the target's memory must be separated from use of
1057 the bytes so obtained by a
1058 .B SECCOMP_IOCTL_NOTIF_ID_VALID
1059 check.
1060 In the above example, the check would be placed between the two final steps.
1061 An example of such a check is shown in EXAMPLES.
1062 .P
1063 Following on from the above, it should be clear that
1064 a write by the supervisor into the target's memory can
1065 .B never
1066 be considered safe.
1067 .\"
1068 .SS Caveats regarding blocking system calls
1069 Suppose that the target performs a blocking system call (e.g.,
1070 .BR accept (2))
1071 that the supervisor should handle.
1072 The supervisor might then in turn execute the same blocking system call.
1073 .P
1074 In this scenario,
1075 it is important to note that if the target's system call is now
1076 interrupted by a signal, the supervisor is
1077 .I not
1078 informed of this.
1079 If the supervisor does not take suitable steps to
1080 actively discover that the target's system call has been canceled,
1081 various difficulties can occur.
1082 Taking the example of
1083 .BR accept (2),
1084 the supervisor might remain blocked in its
1085 .BR accept (2)
1086 holding a port number that the target
1087 (which, after the interruption by the signal handler,
1088 perhaps closed its listening socket)
1089 might expect to be able to reuse in a
1090 .BR bind (2)
1091 call.
1092 .P
1093 Therefore, when the supervisor wishes to emulate a blocking system call,
1094 it must do so in such a way that it gets informed if the target's
1095 system call is interrupted by a signal handler.
1096 For example, if the supervisor itself executes the same
1097 blocking system call, then it could employ a separate thread
1098 that uses the
1099 .B SECCOMP_IOCTL_NOTIF_ID_VALID
1100 operation to check if the target is still blocked in its system call.
1101 Alternatively, in the
1102 .BR accept (2)
1103 example, the supervisor might use
1104 .BR poll (2)
1105 to monitor both the notification file descriptor
1106 (so as to discover when the target's
1107 .BR accept (2)
1108 call has been interrupted) and the listening file descriptor
1109 (so as to know when a connection is available).
1110 .P
1111 If the target's system call is interrupted,
1112 the supervisor must take care to release resources (e.g., file descriptors)
1113 that it acquired on behalf of the target.
1114 .\"
1115 .SS Interaction with SA_RESTART signal handlers
1116 Consider the following scenario:
1117 .IP (1) 5
1118 The target process has used
1119 .BR sigaction (2)
1120 to install a signal handler with the
1121 .B SA_RESTART
1122 flag.
1123 .IP (2)
1124 The target has made a system call that triggered a seccomp
1125 user-space notification and the target is currently blocked
1126 until the supervisor sends a notification response.
1127 .IP (3)
1128 A signal is delivered to the target and the signal handler is executed.
1129 .IP (4)
1130 When (if) the supervisor attempts to send a notification response, the
1131 .B SECCOMP_IOCTL_NOTIF_SEND
1132 .BR ioctl (2))
1133 operation will fail with the
1134 .B ENOENT
1135 error.
1136 .P
1137 In this scenario, the kernel will restart the target's system call.
1138 Consequently, the supervisor will receive another user-space notification.
1139 Thus, depending on how many times the blocked system call
1140 is interrupted by a signal handler,
1141 the supervisor may receive multiple notifications for
1142 the same instance of a system call in the target.
1143 .P
1144 One oddity is that system call restarting as described in this scenario
1145 will occur even for the blocking system calls listed in
1146 .BR signal (7)
1147 that would
1148 .B never
1149 normally be restarted by the
1150 .B SA_RESTART
1151 flag.
1152 .\" FIXME
1153 .\" About the above, Kees Cook commented:
1154 .\"
1155 .\" Does this need fixing? I imagine the correct behavior for this case
1156 .\" would be a response to _SEND of EINPROGRESS and the target would see
1157 .\" EINTR normally?
1158 .\"
1159 .\" I mean, it's not like seccomp doesn't already expose weirdness with
1160 .\" syscall restarts. Not even arm64 compat agrees[3] with arm32 in this
1161 .\" regard. :(
1162 .
1163 .\" FIXME
1164 .\" Michael Kerrisk:
1165 .\" I wonder about the effect of this oddity for system calls that
1166 .\" are normally nonrestartable because they have timeouts. My
1167 .\" understanding is that the kernel doesn't restart those system
1168 .\" calls because it's impossible for the kernel to restart the call
1169 .\" with the right timeout value. I wonder what happens when those
1170 .\" system calls are restarted in the scenario we're discussing.)
1171 .P
1172 Furthermore, if the supervisor response is a file descriptor
1173 added with
1174 .BR SECCOMP_IOCTL_NOTIF_ADDFD ,
1175 then the flag
1176 .B SECCOMP_ADDFD_FLAG_SEND
1177 can be used to atomically add the file descriptor and return that value,
1178 making sure no file descriptors are inadvertently leaked into the target.
1179 .SH BUGS
1180 If a
1181 .B SECCOMP_IOCTL_NOTIF_RECV
1182 .BR ioctl (2)
1183 operation
1184 .\" or a poll/epoll/select
1185 is performed after the target terminates, then the
1186 .BR ioctl (2)
1187 call simply blocks (rather than returning an error to indicate that the
1188 target no longer exists).
1189 .\" FIXME
1190 .\" Comment from Kees Cook:
1191 .\"
1192 .\" I want this fixed. It caused me no end of pain when building the
1193 .\" selftests, and ended up spawning my implementing a global test timeout
1194 .\" in kselftest. :P Before the usage counter refactor, there was no sane
1195 .\" way to deal with this, but now I think we're close.
1196 .\"
1197 .SH EXAMPLES
1198 The (somewhat contrived) program shown below demonstrates the use of
1199 the interfaces described in this page.
1200 The program creates a child process that serves as the "target" process.
1201 The child process installs a seccomp filter that returns the
1202 .B SECCOMP_RET_USER_NOTIF
1203 action value if a call is made to
1204 .BR mkdir (2).
1205 The child process then calls
1206 .BR mkdir (2)
1207 once for each of the supplied command-line arguments,
1208 and reports the result returned by the call.
1209 After processing all arguments, the child process terminates.
1210 .P
1211 The parent process acts as the supervisor, listening for the notifications
1212 that are generated when the target process calls
1213 .BR mkdir (2).
1214 When such a notification occurs,
1215 the supervisor examines the memory of the target process (using
1216 .IR /proc/ pid /mem )
1217 to discover the pathname argument that was supplied to the
1218 .BR mkdir (2)
1219 call, and performs one of the following actions:
1220 .IP \[bu] 3
1221 If the pathname begins with the prefix "/tmp/",
1222 then the supervisor attempts to create the specified directory,
1223 and then spoofs a return for the target process based on the return
1224 value of the supervisor's
1225 .BR mkdir (2)
1226 call.
1227 In the event that that call succeeds,
1228 the spoofed success return value is the length of the pathname.
1229 .IP \[bu]
1230 If the pathname begins with "./" (i.e., it is a relative pathname),
1231 the supervisor sends a
1232 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
1233 response to the kernel to say that the kernel should execute
1234 the target process's
1235 .BR mkdir (2)
1236 call.
1237 .IP \[bu]
1238 If the pathname begins with some other prefix,
1239 the supervisor spoofs an error return for the target process,
1240 so that the target process's
1241 .BR mkdir (2)
1242 call appears to fail with the error
1243 .B EOPNOTSUPP
1244 ("Operation not supported").
1245 Additionally, if the specified pathname is exactly "/bye",
1246 then the supervisor terminates.
1247 .P
1248 This program can be used to demonstrate various aspects of the
1249 behavior of the seccomp user-space notification mechanism.
1250 To help aid such demonstrations,
1251 the program logs various messages to show the operation
1252 of the target process (lines prefixed "T:") and the supervisor
1253 (indented lines prefixed "S:").
1254 .P
1255 In the following example, the target attempts to create the directory
1256 .IR /tmp/x .
1257 Upon receiving the notification, the supervisor creates the directory on the
1258 target's behalf,
1259 and spoofs a success return to be received by the target process's
1260 .BR mkdir (2)
1261 call.
1262 .P
1263 .in +4n
1264 .EX
1265 .RB $ " ./seccomp_unotify /tmp/x" ;
1266 T: PID = 23168
1267 \&
1268 T: about to mkdir("/tmp/x")
1269 S: got notification (ID 0x17445c4a0f4e0e3c) for PID 23168
1270 S: executing: mkdir("/tmp/x", 0700)
1271 S: success! spoofed return = 6
1272 S: sending response (flags = 0; val = 6; error = 0)
1273 T: SUCCESS: mkdir(2) returned 6
1274 \&
1275 T: terminating
1276 S: target has terminated; bye
1277 .EE
1278 .in
1279 .P
1280 In the above output, note that the spoofed return value seen by the target
1281 process is 6 (the length of the pathname
1282 .IR /tmp/x ),
1283 whereas a normal
1284 .BR mkdir (2)
1285 call returns 0 on success.
1286 .P
1287 In the next example, the target attempts to create a directory using the
1288 relative pathname
1289 .IR ./sub .
1290 Since this pathname starts with "./",
1291 the supervisor sends a
1292 .B SECCOMP_USER_NOTIF_FLAG_CONTINUE
1293 response to the kernel,
1294 and the kernel then (successfully) executes the target process's
1295 .BR mkdir (2)
1296 call.
1297 .P
1298 .in +4n
1299 .EX
1300 .RB $ " ./seccomp_unotify ./sub" ;
1301 T: PID = 23204
1302 \&
1303 T: about to mkdir("./sub")
1304 S: got notification (ID 0xddb16abe25b4c12) for PID 23204
1305 S: target can execute system call
1306 S: sending response (flags = 0x1; val = 0; error = 0)
1307 T: SUCCESS: mkdir(2) returned 0
1308 \&
1309 T: terminating
1310 S: target has terminated; bye
1311 .EE
1312 .in
1313 .P
1314 If the target process attempts to create a directory with
1315 a pathname that doesn't start with "." and doesn't begin with the prefix
1316 "/tmp/", then the supervisor spoofs an error return
1317 .RB ( EOPNOTSUPP ,
1318 "Operation not supported")
1319 for the target's
1320 .BR mkdir (2)
1321 call (which is not executed):
1322 .P
1323 .in +4n
1324 .EX
1325 .RB $ " ./seccomp_unotify /xxx" ;
1326 T: PID = 23178
1327 \&
1328 T: about to mkdir("/xxx")
1329 S: got notification (ID 0xe7dc095d1c524e80) for PID 23178
1330 S: spoofing error response (Operation not supported)
1331 S: sending response (flags = 0; val = 0; error = \-95)
1332 T: ERROR: mkdir(2): Operation not supported
1333 \&
1334 T: terminating
1335 S: target has terminated; bye
1336 .EE
1337 .in
1338 .P
1339 In the next example,
1340 the target process attempts to create a directory with the pathname
1341 .BR /tmp/nosuchdir/b .
1342 Upon receiving the notification,
1343 the supervisor attempts to create that directory, but the
1344 .BR mkdir (2)
1345 call fails because the directory
1346 .B /tmp/nosuchdir
1347 does not exist.
1348 Consequently, the supervisor spoofs an error return that passes the error
1349 that it received back to the target process's
1350 .BR mkdir (2)
1351 call.
1352 .P
1353 .in +4n
1354 .EX
1355 .RB $ " ./seccomp_unotify /tmp/nosuchdir/b" ;
1356 T: PID = 23199
1357 \&
1358 T: about to mkdir("/tmp/nosuchdir/b")
1359 S: got notification (ID 0x8744454293506046) for PID 23199
1360 S: executing: mkdir("/tmp/nosuchdir/b", 0700)
1361 S: failure! (errno = 2; No such file or directory)
1362 S: sending response (flags = 0; val = 0; error = \-2)
1363 T: ERROR: mkdir(2): No such file or directory
1364 \&
1365 T: terminating
1366 S: target has terminated; bye
1367 .EE
1368 .in
1369 .P
1370 If the supervisor receives a notification and sees that the
1371 argument of the target's
1372 .BR mkdir (2)
1373 is the string "/bye", then (as well as spoofing an
1374 .B EOPNOTSUPP
1375 error), the supervisor terminates.
1376 If the target process subsequently executes another
1377 .BR mkdir (2)
1378 that triggers its seccomp filter to return the
1379 .B SECCOMP_RET_USER_NOTIF
1380 action value, then the kernel causes the target process's system call to
1381 fail with the error
1382 .B ENOSYS
1383 ("Function not implemented").
1384 This is demonstrated by the following example:
1385 .P
1386 .in +4n
1387 .EX
1388 .RB $ " ./seccomp_unotify /bye /tmp/y" ;
1389 T: PID = 23185
1390 \&
1391 T: about to mkdir("/bye")
1392 S: got notification (ID 0xa81236b1d2f7b0f4) for PID 23185
1393 S: spoofing error response (Operation not supported)
1394 S: sending response (flags = 0; val = 0; error = \-95)
1395 S: terminating **********
1396 T: ERROR: mkdir(2): Operation not supported
1397 \&
1398 T: about to mkdir("/tmp/y")
1399 T: ERROR: mkdir(2): Function not implemented
1400 \&
1401 T: terminating
1402 .EE
1403 .in
1404 .\"
1405 .SS Program source
1406 .\" SRC BEGIN (seccomp_unotify.c)
1407 .EX
1408 #define _GNU_SOURCE
1409 #include <err.h>
1410 #include <errno.h>
1411 #include <fcntl.h>
1412 #include <limits.h>
1413 #include <linux/audit.h>
1414 #include <linux/filter.h>
1415 #include <linux/seccomp.h>
1416 #include <signal.h>
1417 #include <stdbool.h>
1418 #include <stdcountof.h>
1419 #include <stddef.h>
1420 #include <stdint.h>
1421 #include <stdio.h>
1422 #include <stdlib.h>
1423 #include <string.h>
1424 #include <sys/ioctl.h>
1425 #include <sys/prctl.h>
1426 #include <sys/socket.h>
1427 #include <sys/stat.h>
1428 #include <sys/syscall.h>
1429 #include <sys/types.h>
1430 #include <sys/un.h>
1431 #include <unistd.h>
1432 \&
1433 #define streq(...) (strcmp(__VA_ARGS__) == 0)
1434 \&
1435 /* Send the file descriptor \[aq]fd\[aq] over the connected UNIX domain socket
1436 \[aq]sockfd\[aq]. Returns 0 on success, or \-1 on error. */
1437 \&
1438 static int
1439 sendfd(int sockfd, int fd)
1440 {
1441 int data;
1442 struct iovec iov;
1443 struct msghdr msgh;
1444 struct cmsghdr *cmsgp;
1445 \&
1446 /* Allocate a char array of suitable size to hold the ancillary data.
1447 However, since this buffer is in reality a \[aq]struct cmsghdr\[aq], use a
1448 union to ensure that it is suitably aligned. */
1449 union {
1450 char buf[CMSG_SPACE(sizeof(int))];
1451 /* Space large enough to hold an \[aq]int\[aq] */
1452 struct cmsghdr align;
1453 } controlMsg;
1454 \&
1455 /* The \[aq]msg_name\[aq] field can be used to specify the address of the
1456 destination socket when sending a datagram. However, we do not
1457 need to use this field because \[aq]sockfd\[aq] is a connected socket. */
1458 \&
1459 msgh.msg_name = NULL;
1460 msgh.msg_namelen = 0;
1461 \&
1462 /* On Linux, we must transmit at least one byte of real data in
1463 order to send ancillary data. We transmit an arbitrary integer
1464 whose value is ignored by recvfd(). */
1465 \&
1466 msgh.msg_iov = &iov;
1467 msgh.msg_iovlen = 1;
1468 iov.iov_base = &data;
1469 iov.iov_len = sizeof(int);
1470 data = 12345;
1471 \&
1472 /* Set \[aq]msghdr\[aq] fields that describe ancillary data */
1473 \&
1474 msgh.msg_control = controlMsg.buf;
1475 msgh.msg_controllen = sizeof(controlMsg.buf);
1476 \&
1477 /* Set up ancillary data describing file descriptor to send */
1478 \&
1479 cmsgp = CMSG_FIRSTHDR(&msgh);
1480 cmsgp\->cmsg_level = SOL_SOCKET;
1481 cmsgp\->cmsg_type = SCM_RIGHTS;
1482 cmsgp\->cmsg_len = CMSG_LEN(sizeof(int));
1483 memcpy(CMSG_DATA(cmsgp), &fd, sizeof(int));
1484 \&
1485 /* Send real plus ancillary data */
1486 \&
1487 if (sendmsg(sockfd, &msgh, 0) == \-1)
1488 return \-1;
1489 \&
1490 return 0;
1491 }
1492 \&
1493 /* Receive a file descriptor on a connected UNIX domain socket. Returns
1494 the received file descriptor on success, or \-1 on error. */
1495 \&
1496 static int
1497 recvfd(int sockfd)
1498 {
1499 int data, fd;
1500 ssize_t nr;
1501 struct iovec iov;
1502 struct msghdr msgh;
1503 \&
1504 /* Allocate a char buffer for the ancillary data. See the comments
1505 in sendfd() */
1506 union {
1507 char buf[CMSG_SPACE(sizeof(int))];
1508 struct cmsghdr align;
1509 } controlMsg;
1510 struct cmsghdr *cmsgp;
1511 \&
1512 /* The \[aq]msg_name\[aq] field can be used to obtain the address of the
1513 sending socket. However, we do not need this information. */
1514 \&
1515 msgh.msg_name = NULL;
1516 msgh.msg_namelen = 0;
1517 \&
1518 /* Specify buffer for receiving real data */
1519 \&
1520 msgh.msg_iov = &iov;
1521 msgh.msg_iovlen = 1;
1522 iov.iov_base = &data; /* Real data is an \[aq]int\[aq] */
1523 iov.iov_len = sizeof(int);
1524 \&
1525 /* Set \[aq]msghdr\[aq] fields that describe ancillary data */
1526 \&
1527 msgh.msg_control = controlMsg.buf;
1528 msgh.msg_controllen = sizeof(controlMsg.buf);
1529 \&
1530 /* Receive real plus ancillary data; real data is ignored */
1531 \&
1532 nr = recvmsg(sockfd, &msgh, 0);
1533 if (nr == \-1)
1534 return \-1;
1535 \&
1536 cmsgp = CMSG_FIRSTHDR(&msgh);
1537 \&
1538 /* Check the validity of the \[aq]cmsghdr\[aq] */
1539 \&
1540 if (cmsgp == NULL
1541 || cmsgp\->cmsg_len != CMSG_LEN(sizeof(int))
1542 || cmsgp\->cmsg_level != SOL_SOCKET
1543 || cmsgp\->cmsg_type != SCM_RIGHTS)
1544 {
1545 errno = EINVAL;
1546 return \-1;
1547 }
1548 \&
1549 /* Return the received file descriptor to our caller */
1550 \&
1551 memcpy(&fd, CMSG_DATA(cmsgp), sizeof(int));
1552 return fd;
1553 }
1554 \&
1555 static void
1556 sigchldHandler(int sig)
1557 {
1558 char msg[] = "\[rs]tS: target has terminated; bye\[rs]n";
1559 \&
1560 write(STDOUT_FILENO, msg, sizeof(msg) \- 1);
1561 _exit(EXIT_SUCCESS);
1562 }
1563 \&
1564 static int
1565 seccomp(unsigned int operation, unsigned int flags, void *args)
1566 {
1567 return syscall(SYS_seccomp, operation, flags, args);
1568 }
1569 \&
1570 /* The following is the x86\-64\-specific BPF boilerplate code for checking
1571 that the BPF program is running on the right architecture + ABI. At
1572 completion of these instructions, the accumulator contains the system
1573 call number. */
1574 \&
1575 /* For the x32 ABI, all system call numbers have bit 30 set */
1576 \&
1577 #define X32_SYSCALL_BIT 0x40000000
1578 \&
1579 #define X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR \[rs]
1580 BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \[rs]
1581 (offsetof(struct seccomp_data, arch))), \[rs]
1582 BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, AUDIT_ARCH_X86_64, 0, 2), \[rs]
1583 BPF_STMT(BPF_LD | BPF_W | BPF_ABS, \[rs]
1584 (offsetof(struct seccomp_data, nr))), \[rs]
1585 BPF_JUMP(BPF_JMP | BPF_JGE | BPF_K, X32_SYSCALL_BIT, 0, 1), \[rs]
1586 BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL_PROCESS)
1587 \&
1588 /* installNotifyFilter() installs a seccomp filter that generates
1589 user\-space notifications (SECCOMP_RET_USER_NOTIF) when the process
1590 calls mkdir(2); the filter allows all other system calls.
1591 \&
1592 The function return value is a file descriptor from which the
1593 user\-space notifications can be fetched. */
1594 \&
1595 static int
1596 installNotifyFilter(void)
1597 {
1598 int notifyFd;
1599 \&
1600 struct sock_filter filter[] = {
1601 X86_64_CHECK_ARCH_AND_LOAD_SYSCALL_NR,
1602 \&
1603 /* mkdir() triggers notification to user\-space supervisor */
1604 \&
1605 BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, SYS_mkdir, 0, 1),
1606 BPF_STMT(BPF_RET + BPF_K, SECCOMP_RET_USER_NOTIF),
1607 \&
1608 /* Every other system call is allowed */
1609 \&
1610 BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW),
1611 };
1612 \&
1613 struct sock_fprog prog = {
1614 .len = countof(filter),
1615 .filter = filter,
1616 };
1617 \&
1618 /* Install the filter with the SECCOMP_FILTER_FLAG_NEW_LISTENER flag;
1619 as a result, seccomp() returns a notification file descriptor. */
1620 \&
1621 notifyFd = seccomp(SECCOMP_SET_MODE_FILTER,
1622 SECCOMP_FILTER_FLAG_NEW_LISTENER, &prog);
1623 if (notifyFd == \-1)
1624 err(EXIT_FAILURE, "seccomp\-install\-notify\-filter");
1625 \&
1626 return notifyFd;
1627 }
1628 \&
1629 /* Close a pair of sockets created by socketpair() */
1630 \&
1631 static void
1632 closeSocketPair(int sockPair[2])
1633 {
1634 if (close(sockPair[0]) == \-1)
1635 err(EXIT_FAILURE, "closeSocketPair\-close\-0");
1636 if (close(sockPair[1]) == \-1)
1637 err(EXIT_FAILURE, "closeSocketPair\-close\-1");
1638 }
1639 \&
1640 /* Implementation of the target process. Create a child process that:
1641 \&
1642 (1) installs a seccomp filter with the
1643 SECCOMP_FILTER_FLAG_NEW_LISTENER flag;
1644 (2) writes the seccomp notification file descriptor returned from
1645 the previous step onto the UNIX domain socket, \[aq]sockPair[0]\[aq];
1646 (3) calls mkdir(2) for each element of \[aq]argv\[aq].
1647 \&
1648 The function return value in the parent is the PID of the child
1649 process; the child does not return from this function. */
1650 \&
1651 static pid_t
1652 targetProcess(int sockPair[2], char *argv[])
1653 {
1654 int notifyFd, s;
1655 pid_t targetPid;
1656 \&
1657 targetPid = fork();
1658 \&
1659 if (targetPid == \-1)
1660 err(EXIT_FAILURE, "fork");
1661 \&
1662 if (targetPid > 0) /* In parent, return PID of child */
1663 return targetPid;
1664 \&
1665 /* Child falls through to here */
1666 \&
1667 printf("T: PID = %ld\[rs]n", (long) getpid());
1668 \&
1669 /* Install seccomp filter(s) */
1670 \&
1671 if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0))
1672 err(EXIT_FAILURE, "prctl");
1673 \&
1674 notifyFd = installNotifyFilter();
1675 \&
1676 /* Pass the notification file descriptor to the tracing process over
1677 a UNIX domain socket */
1678 \&
1679 if (sendfd(sockPair[0], notifyFd) == \-1)
1680 err(EXIT_FAILURE, "sendfd");
1681 \&
1682 /* Notification and socket FDs are no longer needed in target */
1683 \&
1684 if (close(notifyFd) == \-1)
1685 err(EXIT_FAILURE, "close\-target\-notify\-fd");
1686 \&
1687 closeSocketPair(sockPair);
1688 \&
1689 /* Perform a mkdir() call for each of the command\-line arguments */
1690 \&
1691 for (char **ap = argv; *ap != NULL; ap++) {
1692 printf("\[rs]nT: about to mkdir(\[rs]"%s\[rs]")\[rs]n", *ap);
1693 \&
1694 s = mkdir(*ap, 0700);
1695 if (s == \-1)
1696 perror("T: ERROR: mkdir(2)");
1697 else
1698 printf("T: SUCCESS: mkdir(2) returned %d\[rs]n", s);
1699 }
1700 \&
1701 printf("\[rs]nT: terminating\[rs]n");
1702 exit(EXIT_SUCCESS);
1703 }
1704 \&
1705 /* Check that the notification ID provided by a SECCOMP_IOCTL_NOTIF_RECV
1706 operation is still valid. It will no longer be valid if the target
1707 process has terminated or is no longer blocked in the system call that
1708 generated the notification (because it was interrupted by a signal).
1709 \&
1710 This operation can be used when doing such things as accessing
1711 /proc/PID files in the target process in order to avoid TOCTOU race
1712 conditions where the PID that is returned by SECCOMP_IOCTL_NOTIF_RECV
1713 terminates and is reused by another process. */
1714 \&
1715 static bool
1716 cookieIsValid(int notifyFd, uint64_t id)
1717 {
1718 return ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_ID_VALID, &id) == 0;
1719 }
1720 \&
1721 /* Access the memory of the target process in order to fetch the
1722 pathname referred to by the system call argument \[aq]argNum\[aq] in
1723 \[aq]req\->data.args[]\[aq]. The pathname is returned in \[aq]path\[aq],
1724 a buffer of \[aq]size\[aq] bytes allocated by the caller.
1725 \&
1726 Returns true if the pathname is successfully fetched, and false
1727 otherwise. For possible causes of failure, see the comments below. */
1728 \&
1729 static bool
1730 getTargetPathname(struct seccomp_notif *req, int notifyFd,
1731 int argNum, char *path, size_t size)
1732 {
1733 int procMemFd;
1734 char procMemPath[PATH_MAX];
1735 ssize_t nread;
1736 \&
1737 snprintf(procMemPath, sizeof(procMemPath), "/proc/%d/mem", req\->pid);
1738 \&
1739 procMemFd = open(procMemPath, O_RDONLY | O_CLOEXEC);
1740 if (procMemFd == \-1)
1741 return false;
1742 \&
1743 /* Check that the process whose info we are accessing is still alive
1744 and blocked in the system call that caused the notification.
1745 If the SECCOMP_IOCTL_NOTIF_ID_VALID operation (performed in
1746 cookieIsValid()) succeeded, we know that the /proc/PID/mem file
1747 descriptor that we opened corresponded to the process for which we
1748 received a notification. If that process subsequently terminates,
1749 then read() on that file descriptor will return 0 (EOF). */
1750 \&
1751 if (!cookieIsValid(notifyFd, req\->id)) {
1752 close(procMemFd);
1753 return false;
1754 }
1755 \&
1756 /* Read bytes at the location containing the pathname argument */
1757 \&
1758 nread = pread(procMemFd, path, size, req\->data.args[argNum]);
1759 \&
1760 close(procMemFd);
1761 \&
1762 if (nread <= 0)
1763 return false;
1764 \&
1765 /* Once again check that the notification ID is still valid. The
1766 case we are particularly concerned about here is that just
1767 before we fetched the pathname, the target\[aq]s blocked system
1768 call was interrupted by a signal handler, and after the handler
1769 returned, the target carried on execution (past the interrupted
1770 system call). In that case, we have no guarantees about what we
1771 are reading, since the target\[aq]s memory may have been arbitrarily
1772 changed by subsequent operations. */
1773 \&
1774 if (!cookieIsValid(notifyFd, req\->id)) {
1775 perror("\[rs]tS: notification ID check failed!!!");
1776 return false;
1777 }
1778 \&
1779 /* Even if the target\[aq]s system call was not interrupted by a signal,
1780 we have no guarantees about what was in the memory of the target
1781 process. (The memory may have been modified by another thread, or
1782 even by an external attacking process.) We therefore treat the
1783 buffer returned by pread() as untrusted input. The buffer should
1784 contain a terminating null byte; if not, then we will trigger an
1785 error for the target process. */
1786 \&
1787 if (strnlen(path, nread) < nread)
1788 return true;
1789 \&
1790 return false;
1791 }
1792 \&
1793 /* Allocate buffers for the seccomp user\-space notification request and
1794 response structures. It is the caller\[aq]s responsibility to free the
1795 buffers returned via \[aq]req\[aq] and \[aq]resp\[aq]. */
1796 \&
1797 static void
1798 allocSeccompNotifBuffers(struct seccomp_notif **req,
1799 struct seccomp_notif_resp **resp,
1800 struct seccomp_notif_sizes *sizes)
1801 {
1802 size_t resp_size;
1803 \&
1804 /* Discover the sizes of the structures that are used to receive
1805 notifications and send notification responses, and allocate
1806 buffers of those sizes. */
1807 \&
1808 if (seccomp(SECCOMP_GET_NOTIF_SIZES, 0, sizes) == \-1)
1809 err(EXIT_FAILURE, "seccomp\-SECCOMP_GET_NOTIF_SIZES");
1810 \&
1811 *req = malloc(sizes\->seccomp_notif);
1812 if (*req == NULL)
1813 err(EXIT_FAILURE, "malloc\-seccomp_notif");
1814 \&
1815 /* When allocating the response buffer, we must allow for the fact
1816 that the user\-space binary may have been built with user\-space
1817 headers where \[aq]struct seccomp_notif_resp\[aq] is bigger than the
1818 response buffer expected by the (older) kernel. Therefore, we
1819 allocate a buffer that is the maximum of the two sizes. This
1820 ensures that if the supervisor places bytes into the response
1821 structure that are past the response size that the kernel expects,
1822 then the supervisor is not touching an invalid memory location. */
1823 \&
1824 resp_size = sizes\->seccomp_notif_resp;
1825 if (sizeof(struct seccomp_notif_resp) > resp_size)
1826 resp_size = sizeof(struct seccomp_notif_resp);
1827 \&
1828 *resp = malloc(resp_size);
1829 if (*resp == NULL)
1830 err(EXIT_FAILURE, "malloc\-seccomp_notif_resp");
1831 \&
1832 }
1833 \&
1834 /* Handle notifications that arrive via the SECCOMP_RET_USER_NOTIF file
1835 descriptor, \[aq]notifyFd\[aq]. */
1836 \&
1837 static void
1838 handleNotifications(int notifyFd)
1839 {
1840 bool pathOK;
1841 char path[PATH_MAX];
1842 struct seccomp_notif *req;
1843 struct seccomp_notif_resp *resp;
1844 struct seccomp_notif_sizes sizes;
1845 \&
1846 allocSeccompNotifBuffers(&req, &resp, &sizes);
1847 \&
1848 /* Loop handling notifications */
1849 \&
1850 for (;;) {
1851 \&
1852 /* Wait for next notification, returning info in \[aq]*req\[aq] */
1853 \&
1854 memset(req, 0, sizes.seccomp_notif);
1855 if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_RECV, req) == \-1) {
1856 if (errno == EINTR)
1857 continue;
1858 err(EXIT_FAILURE, "\[rs]tS: ioctl\-SECCOMP_IOCTL_NOTIF_RECV");
1859 }
1860 \&
1861 printf("\[rs]tS: got notification (ID %#llx) for PID %d\[rs]n",
1862 req\->id, req\->pid);
1863 \&
1864 /* The only system call that can generate a notification event
1865 is mkdir(2). Nevertheless, we check that the notified system
1866 call is indeed mkdir() as kind of future\-proofing of this
1867 code in case the seccomp filter is later modified to
1868 generate notifications for other system calls. */
1869 \&
1870 if (req\->data.nr != SYS_mkdir) {
1871 printf("\[rs]tS: notification contained unexpected "
1872 "system call number; bye!!!\[rs]n");
1873 exit(EXIT_FAILURE);
1874 }
1875 \&
1876 pathOK = getTargetPathname(req, notifyFd, 0, path, sizeof(path));
1877 \&
1878 /* Prepopulate some fields of the response */
1879 \&
1880 resp\->id = req\->id; /* Response includes notification ID */
1881 resp\->flags = 0;
1882 resp\->val = 0;
1883 \&
1884 /* If getTargetPathname() failed, trigger an EINVAL error
1885 response (sending this response may yield an error if the
1886 failure occurred because the notification ID was no longer
1887 valid); if the directory is in /tmp, then create it on behalf
1888 of the supervisor; if the pathname starts with \[aq].\[aq], tell the
1889 kernel to let the target process execute the mkdir();
1890 otherwise, give an error for a directory pathname in any other
1891 location. */
1892 \&
1893 if (!pathOK) {
1894 resp\->error = \-EINVAL;
1895 printf("\[rs]tS: spoofing error for invalid pathname (%s)\[rs]n",
1896 strerror(\-resp\->error));
1897 } else if (strncmp(path, "/tmp/", strlen("/tmp/")) == 0) {
1898 printf("\[rs]tS: executing: mkdir(\[rs]"%s\[rs]", %#llo)\[rs]n",
1899 path, req\->data.args[1]);
1900 \&
1901 if (mkdir(path, req\->data.args[1]) == 0) {
1902 resp\->error = 0; /* "Success" */
1903 resp\->val = strlen(path); /* Used as return value of
1904 mkdir() in target */
1905 printf("\[rs]tS: success! spoofed return = %lld\[rs]n",
1906 resp\->val);
1907 } else {
1908 \&
1909 /* If mkdir() failed in the supervisor, pass the error
1910 back to the target */
1911 \&
1912 resp\->error = \-errno;
1913 printf("\[rs]tS: failure! (errno = %d; %s)\[rs]n", errno,
1914 strerror(errno));
1915 }
1916 } else if (strncmp(path, "./", strlen("./")) == 0) {
1917 resp\->error = resp\->val = 0;
1918 resp\->flags = SECCOMP_USER_NOTIF_FLAG_CONTINUE;
1919 printf("\[rs]tS: target can execute system call\[rs]n");
1920 } else {
1921 resp\->error = \-EOPNOTSUPP;
1922 printf("\[rs]tS: spoofing error response (%s)\[rs]n",
1923 strerror(\-resp\->error));
1924 }
1925 \&
1926 /* Send a response to the notification */
1927 \&
1928 printf("\[rs]tS: sending response "
1929 "(flags = %#x; val = %lld; error = %d)\[rs]n",
1930 resp\->flags, resp\->val, resp\->error);
1931 \&
1932 if (ioctl(notifyFd, SECCOMP_IOCTL_NOTIF_SEND, resp) == \-1) {
1933 if (errno == ENOENT)
1934 printf("\[rs]tS: response failed with ENOENT; "
1935 "perhaps target process\[aq]s syscall was "
1936 "interrupted by a signal?\[rs]n");
1937 else
1938 perror("ioctl\-SECCOMP_IOCTL_NOTIF_SEND");
1939 }
1940 \&
1941 /* If the pathname is just "/bye", then the supervisor breaks out
1942 of the loop and terminates. This allows us to see what happens
1943 if the target process makes further calls to mkdir(2). */
1944 \&
1945 if (streq(path, "/bye"))
1946 break;
1947 }
1948 \&
1949 free(req);
1950 free(resp);
1951 printf("\[rs]tS: terminating **********\[rs]n");
1952 exit(EXIT_FAILURE);
1953 }
1954 \&
1955 /* Implementation of the supervisor process:
1956 \&
1957 (1) obtains the notification file descriptor from \[aq]sockPair[1]\[aq]
1958 (2) handles notifications that arrive on that file descriptor. */
1959 \&
1960 static void
1961 supervisor(int sockPair[2])
1962 {
1963 int notifyFd;
1964 \&
1965 notifyFd = recvfd(sockPair[1]);
1966 \&
1967 if (notifyFd == \-1)
1968 err(EXIT_FAILURE, "recvfd");
1969 \&
1970 closeSocketPair(sockPair); /* We no longer need the socket pair */
1971 \&
1972 handleNotifications(notifyFd);
1973 }
1974 \&
1975 int
1976 main(int argc, char *argv[])
1977 {
1978 int sockPair[2];
1979 struct sigaction sa;
1980 \&
1981 setbuf(stdout, NULL);
1982 \&
1983 if (argc < 2) {
1984 fprintf(stderr, "At least one pathname argument is required\[rs]n");
1985 exit(EXIT_FAILURE);
1986 }
1987 \&
1988 /* Create a UNIX domain socket that is used to pass the seccomp
1989 notification file descriptor from the target process to the
1990 supervisor process. */
1991 \&
1992 if (socketpair(AF_UNIX, SOCK_STREAM, 0, sockPair) == \-1)
1993 err(EXIT_FAILURE, "socketpair");
1994 \&
1995 /* Create a child process\-\-the "target"\-\-that installs seccomp
1996 filtering. The target process writes the seccomp notification
1997 file descriptor onto \[aq]sockPair[0]\[aq] and then calls mkdir(2) for
1998 each directory in the command\-line arguments. */
1999 \&
2000 (void) targetProcess(sockPair, &argv[optind]);
2001 \&
2002 /* Catch SIGCHLD when the target terminates, so that the
2003 supervisor can also terminate. */
2004 \&
2005 sa.sa_handler = sigchldHandler;
2006 sa.sa_flags = 0;
2007 sigemptyset(&sa.sa_mask);
2008 if (sigaction(SIGCHLD, &sa, NULL) == \-1)
2009 err(EXIT_FAILURE, "sigaction");
2010 \&
2011 supervisor(sockPair);
2012 \&
2013 exit(EXIT_SUCCESS);
2014 }
2015 .EE
2016 .\" SRC END
2017 .SH SEE ALSO
2018 .BR ioctl (2),
2019 .BR pidfd_getfd (2),
2020 .BR pidfd_open (2),
2021 .BR seccomp (2)
2022 .P
2023 A further example program can be found in the kernel source file
2024 .IR samples/seccomp/user-trap.c .