1seccomp_notify_alloc(3) libseccomp Documentation seccomp_notify_alloc(3)
2
6 seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive, sec‐
7 comp_notify_respond, seccomp_notify_id_valid, seccomp_notify_fd - Man‐
8 age seccomp notifications
9
11 #include <seccomp.h>
12 int seccomp_notify_alloc(struct seccomp_notif **req, struct seccomp_notif_resp **resp)
14 void seccomp_notify_free(struct seccomp_notif *req, struct seccomp_notif_resp *resp)
15 int seccomp_notify_receive(int fd, struct seccomp_notif *req)
16 int seccomp_notify_respond(int fd, struct seccomp_notif_resp *resp)
17 int seccomp_notify_id_valid(int fd, uint64_t id)
18 int seccomp_notify_fd(const scmp_filter_ctx ctx)
19 Link with -lseccomp.
21
23 The seccomp_notify_alloc() function dynamically allocates enough memory
24 for a seccomp notification and response. Note that one should always
25 use these functions and not depend on the structure sizes in headers,
26 since the size can vary depending on the kernel version. This function
27 takes care to ask the kernel how big each structure should be, and
28 allocates the right amount of memory. The seccomp_notify_free() func‐
29 tion frees memory allocated by seccomp_notify_alloc().
30 The seccomp_notify_receive() function receives a notification from a
32 seccomp notify fd (obtained from seccomp_notify_fd()).
33 The seccomp_notify_respond() function sends a response to a particular
35 notification. The id field should be the same as the id from the
36 request, so that the kernel knows which request this response corre‐
37 sponds to.
38 The seccomp_notify_id_valid() function checks to see if the syscall
40 from a particular notification request is still valid, i.e. if the task
41 is still alive. See NOTES below for details on race conditions.
42 The seccomp_notify_fd() returns the notification fd of a filter after
44 it has been loaded.
45
47 The seccomp_notify_fd() returns the notification fd of the loaded fil‐
48 ter, -1 if a notification fd has not yet been created, and -EINVAL if
49 the filter context is invalid.
50 The seccomp_notify_id_valid() returns 0 if the id is valid, and -ENOENT
52 if it is not.
53 The seccomp_notify_alloc(), seccomp_notify_receive(), and sec‐
55 comp_notify_respond() functions return zero on success, or one of the
56 following error codes on failure:
57 -ECANCELED
59 There was a system failure beyond the control of the library,
60 check the errno value for more information.
61 -EFAULT
63 Internal libseccomp failure.
64 -ENOMEM
66 The library was unable to allocate enough memory.
67 -EOPNOTSUPP
69 The library doesn't support the particular operation.
70
72 Care should be taken to avoid two different time of check/time of use
73 errors. First, after opening any resources relevant to the pid for a
74 notification (e.g. /proc/pid/mem for reading tracee memory to make
75 policy decisions), applications should call seccomp_notify_id_valid()
76 to make sure that the resources the application has opened correspond
77 to the right pid, i.e. that the pid didn't die and a different task
78 take its place.
79 Second, the classic time of check/time of use issue with seccomp memory
81 should also be avoided: applications should copy any memory they wish
82 to use to make decisions from the tracee into its own address space
83 before applying any policy decisions, since a multi-threaded tracee may
84 edit the memory at any time, including after it's used to make a policy
85 decision.
86 A complete example of how to avoid these two races is available in the
88 Linux Kernel source tree at /samples/seccomp/user-trap.c.
89
91 Tycho Andersen <tycho@tycho.ws>
92tycho@tycho.ws 30 May 2020 seccomp_notify_alloc(3)