diff options
Diffstat (limited to 'doc/man/man3')
32 files changed, 2032 insertions, 0 deletions
diff --git a/doc/man/man3/seccomp_api_get.3 b/doc/man/man3/seccomp_api_get.3 new file mode 100644 index 0000000..ea2ea75 --- /dev/null +++ b/doc/man/man3/seccomp_api_get.3 @@ -0,0 +1,111 @@ +.TH "seccomp_api_get" 3 "6 November 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_api_get, seccomp_api_set \- Manage the libseccomp API level +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.BI "const unsigned int seccomp_api_get(" void ");" +.BI "int seccomp_api_set(unsigned int " level ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_api_get () +function returns an integer representing the functionality ("API level") +provided by the current running kernel. It is important to note that while +.BR seccomp_api_get () +can be called multiple times, the kernel is only probed the first time to see +what functionality is supported, all following calls to +.BR seccomp_api_get () +return a cached value. +.P +The +.BR seccomp_api_set () +function allows callers to force the API level to the provided value; however, +this is almost always a bad idea and use of this function is strongly +discouraged. +.P +The different API level values are described below: +.TP +.B 0 +Reserved value, not currently used. +.TP +.B 1 +Base level support. +.TP +.B 2 +The SCMP_FLTATR_CTL_TSYNC filter attribute is supported and libseccomp uses +the +.BR seccomp(2) +syscall to load the seccomp filter into the kernel. +.TP +.B 3 +The SCMP_FLTATR_CTL_LOG filter attribute and the SCMP_ACT_LOG action are +supported. +.TP +.B 4 +The SCMP_FLTATR_CTL_SSB filter attribute is supported. +.TP +.B 5 +The SCMP_ACT_NOTIFY action and the notify APIs are supported. +.TP +.B 6 +The simultaneous use of SCMP_FLTATR_CTL_TSYNC and the notify APIs are supported. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_api_get () +function returns an integer representing the supported API level. The +.BR seccomp_api_set () +function returns zero on success, negative values on failure. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + unsigned int api; + + api = seccomp_api_get(); + switch (api) { + case 2: + /* ... */ + default: + /* ... */ + } + + return 0; + +err: + return 1; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// diff --git a/doc/man/man3/seccomp_api_set.3 b/doc/man/man3/seccomp_api_set.3 new file mode 100644 index 0000000..6ed16f8 --- /dev/null +++ b/doc/man/man3/seccomp_api_set.3 @@ -0,0 +1 @@ +.so man3/seccomp_api_get.3 diff --git a/doc/man/man3/seccomp_arch_add.3 b/doc/man/man3/seccomp_arch_add.3 new file mode 100644 index 0000000..da6ee76 --- /dev/null +++ b/doc/man/man3/seccomp_arch_add.3 @@ -0,0 +1,163 @@ +.TH "seccomp_arch_add" 3 "15 June 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_arch_add, seccomp_arch_remove, seccomp_arch_exist, seccomp_arch_native \- Manage seccomp filter architectures +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.B #define SCMP_ARCH_NATIVE +.B #define SCMP_ARCH_X86 +.B #define SCMP_ARCH_X86_64 +.B #define SCMP_ARCH_X32 +.B #define SCMP_ARCH_ARM +.B #define SCMP_ARCH_AARCH64 +.B #define SCMP_ARCH_MIPS +.B #define SCMP_ARCH_MIPS64 +.B #define SCMP_ARCH_MIPS64N32 +.B #define SCMP_ARCH_MIPSEL +.B #define SCMP_ARCH_MIPSEL64 +.B #define SCMP_ARCH_MIPSEL64N32 +.B #define SCMP_ARCH_PPC +.B #define SCMP_ARCH_PPC64 +.B #define SCMP_ARCH_PPC64LE +.B #define SCMP_ARCH_S390 +.B #define SCMP_ARCH_S390X +.B #define SCMP_ARCH_PARISC +.B #define SCMP_ARCH_PARISC64 +.B #define SCMP_ARCH_RISCV64 +.sp +.BI "uint32_t seccomp_arch_resolve_name(const char *" arch_name ");" +.BI "uint32_t seccomp_arch_native();" +.BI "int seccomp_arch_exist(const scmp_filter_ctx " ctx ", uint32_t " arch_token ");" +.BI "int seccomp_arch_add(scmp_filter_ctx " ctx ", uint32_t " arch_token ");" +.BI "int seccomp_arch_remove(scmp_filter_ctx " ctx ", uint32_t " arch_token ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_arch_exist () +function tests to see if a given architecture has been added to the seccomp +filter in +.IR ctx , +where the +.BR seccomp_arch_add () +and +.BR seccomp_arch_remove () +add and remove, respectively, architectures from the seccomp filter. In all +three functions, the architecture values given in +.I arch_token +should be the +.BR SCMP_ARCH_* +defined constants; with the +.BR SCMP_ARCH_NATIVE +constant always referring to the native compiled architecture. The +.BR seccomp_arch_native () +function returns the system's architecture such that it will match one of the +.BR SCMP_ARCH_* +constants. While the +.BR seccomp_arch_resolve_name () +function also returns a +.BR SCMP_ARCH_* +constant, the returned token matches the name of the architecture +passed as an argument to the function. +.P +When a seccomp filter is initialized with the call to +.BR seccomp_init (3) +the native architecture is automatically added to the filter. +.P +While it is possible to remove all architectures from a filter, most of the +libseccomp APIs will fail if the filter does not contain at least one +architecture. +.P +When adding a new architecture to an existing filter, the existing rules will +not be added to the new architecture. However, rules added after adding the +new architecture will be added to all of the architectures in the filter. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_arch_add (), +.BR seccomp_arch_remove (), +and +.BR seccomp_arch_exist () +functions return zero on success or one of the following error codes on +failure: +.TP +.B -EDOM +Architecture specific failure. +.TP +.B -EEXIST +In the case of +.BR seccomp_arch_add () +the architecture already exists and in the case of +.BR seccomp_arch_remove () +the architecture does not exist. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + if (seccomp_arch_exist(ctx, SCMP_ARCH_X86) == \-EEXIST) { + rc = seccomp_arch_add(ctx, SCMP_ARCH_X86); + if (rc != 0) + goto out_all; + rc = seccomp_arch_remove(ctx, SCMP_ARCH_NATIVE); + if (rc != 0) + goto out_all; + } + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_reset (3), +.BR seccomp_merge (3) diff --git a/doc/man/man3/seccomp_arch_exist.3 b/doc/man/man3/seccomp_arch_exist.3 new file mode 100644 index 0000000..f72602b --- /dev/null +++ b/doc/man/man3/seccomp_arch_exist.3 @@ -0,0 +1 @@ +.so man3/seccomp_arch_add.3 diff --git a/doc/man/man3/seccomp_arch_native.3 b/doc/man/man3/seccomp_arch_native.3 new file mode 100644 index 0000000..f72602b --- /dev/null +++ b/doc/man/man3/seccomp_arch_native.3 @@ -0,0 +1 @@ +.so man3/seccomp_arch_add.3 diff --git a/doc/man/man3/seccomp_arch_remove.3 b/doc/man/man3/seccomp_arch_remove.3 new file mode 100644 index 0000000..f72602b --- /dev/null +++ b/doc/man/man3/seccomp_arch_remove.3 @@ -0,0 +1 @@ +.so man3/seccomp_arch_add.3 diff --git a/doc/man/man3/seccomp_arch_resolve_name.3 b/doc/man/man3/seccomp_arch_resolve_name.3 new file mode 100644 index 0000000..f72602b --- /dev/null +++ b/doc/man/man3/seccomp_arch_resolve_name.3 @@ -0,0 +1 @@ +.so man3/seccomp_arch_add.3 diff --git a/doc/man/man3/seccomp_attr_get.3 b/doc/man/man3/seccomp_attr_get.3 new file mode 100644 index 0000000..c1e85be --- /dev/null +++ b/doc/man/man3/seccomp_attr_get.3 @@ -0,0 +1 @@ +.so man3/seccomp_attr_set.3 diff --git a/doc/man/man3/seccomp_attr_set.3 b/doc/man/man3/seccomp_attr_set.3 new file mode 100644 index 0000000..4341abc --- /dev/null +++ b/doc/man/man3/seccomp_attr_set.3 @@ -0,0 +1,202 @@ +.TH "seccomp_attr_set" 3 "06 June 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_attr_set, seccomp_attr_get \- Manage the seccomp filter attributes +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.B enum scmp_filter_attr; +.sp +.BI "int seccomp_attr_set(scmp_filter_ctx " ctx "," +.BI " enum scmp_filter_attr " attr ", uint32_t " value ");" +.BI "int seccomp_attr_get(scmp_filter_ctx " ctx "," +.BI " enum scmp_filter_attr " attr ", uint32_t *" value ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_attr_set () +function sets the different seccomp filter attributes while the +.BR seccomp_attr_get () +function fetches the filter attributes. The seccomp filter attributes are +tunable values that affect how the library behaves when generating and loading +the seccomp filter into the kernel. The attributes are reset to their default +values whenever the filter is initialized or reset via +.BR seccomp_init (3) +or +.BR seccomp_reset (3). +.P +The filter context +.I ctx +is the value returned by the call to +.BR seccomp_init (3). +.P +Valid +.I attr +values are as follows: +.TP +.B SCMP_FLTATR_ACT_DEFAULT +The default filter action as specified in the call to +.BR seccomp_init (3) +or +.BR seccomp_reset (3). +This attribute is read-only. +.TP +.B SCMP_FLTATR_ACT_BADARCH +The filter action taken when the loaded filter does not match the architecture +of the executing application. Defaults to the +.B SCMP_ACT_KILL +action. +.TP +.B SCMP_FLTATR_CTL_NNP +A flag to specify if the NO_NEW_PRIVS functionality should be enabled before +loading the seccomp filter into the kernel. Setting this to off +.RI ( value +== 0) results in no action, meaning that loading the seccomp filter into the +kernel will fail if CAP_SYS_ADMIN is missing and NO_NEW_PRIVS has not been +externally set. Defaults to on +.RI ( value +== 1). +.TP +.B SCMP_FLTATR_CTL_TSYNC +A flag to specify if the kernel should attempt to synchronize the filters +across all threads on +.BR seccomp_load (3). +If the kernel is unable to synchronize all of the thread then the load +operation will fail. This flag is only available on Linux Kernel 3.17 or +greater; attempting to enable this flag on earlier kernels will result in an +error being returned. Defaults to off +.RI ( value +== 0). +.TP +.B SCMP_FLTATR_API_TSKIP +A flag to specify if libseccomp should allow filter rules to be created for +the -1 syscall. The -1 syscall value can be used by tracer programs to skip +specific syscall invocations, see +.BR seccomp (2) +for more information. Defaults to off +.RI ( value +== 0). +.TP +.B SCMP_FLTATR_CTL_LOG +A flag to specify if the kernel should log all filter actions taken except for +the +.BR SCMP_ACT_ALLOW +action. Defaults to off +.RI ( value +== 0). +.TP +.B SCMP_FLTATR_CTL_SSB +A flag to disable Speculative Store Bypass mitigations for this filter. +Defaults to off +.RI ( value +== 0). +.TP +.B SCMP_FLTATR_CTL_OPTIMIZE +A flag to specify the optimization level of the seccomp filter. By default +libseccomp generates a set of sequential \'if\' statements for each rule in +the filter. +.BR seccomp_syscall_priority (3) +can be used to prioritize the order for the default cause. The binary tree +optimization sorts by syscall numbers and generates consistent +.BR O(log\ n) +filter traversal for every rule in the filter. The binary tree may be +advantageous for large filters. Note that +.BR seccomp_syscall_priority (3) +is ignored when SCMP_FLTATR_CTL_OPTIMIZE == 2. +.RS +.P +The different optimization levels are described below: +.TP +.B 0 +Reserved value, not currently used. +.TP +.B 1 +Rules sorted by priority and complexity (DEFAULT). +.TP +.B 2 +Binary tree sorted by syscall number. +.RE +.TP +.B SCMP_FLTATR_API_SYSRAWRC +A flag to specify if libseccomp should pass system error codes back to the +caller instead of the default -ECANCELED. Defaults to off +.RI ( value +== 0). +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +Returns zero on success or one of the following error codes on +failure: +.TP +.B -EACCES +Setting the attribute with the given value is not allowed. +.TP +.B -EEXIST +The attribute does not exist. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -EOPNOTSUPP +The library doesn't support the particular operation. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_ALLOW); + if (ctx == NULL) + goto out; + + /* ... */ + + rc = seccomp_attr_set(ctx, SCMP_FLTATR_ACT_BADARCH, SCMP_ACT_TRAP); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_reset (3), +.BR seccomp_load (3), +.BR seccomp (2) diff --git a/doc/man/man3/seccomp_export_bpf.3 b/doc/man/man3/seccomp_export_bpf.3 new file mode 100644 index 0000000..9ce06df --- /dev/null +++ b/doc/man/man3/seccomp_export_bpf.3 @@ -0,0 +1,126 @@ +.TH "seccomp_export_bpf" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_export_bpf, seccomp_export_pfc \- Export the seccomp filter +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "int seccomp_export_bpf(const scmp_filter_ctx " ctx ", int " fd ");" +.BI "int seccomp_export_pfc(const scmp_filter_ctx " ctx ", int " fd ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_export_bpf () +and +.BR seccomp_export_pfc () +functions generate and output the current seccomp filter in either BPF (Berkeley +Packet Filter) or PFC (Pseudo Filter Code). The output of +.BR seccomp_export_bpf () +is suitable for loading into the kernel, while the output of +.BR seccomp_export_pfc () +is human readable and is intended primarily as a debugging tool for developers +using libseccomp. Both functions write the filter to the +.I fd +file descriptor. +.P +The filter context +.I ctx +is the value returned by the call to +.BR seccomp_init (3). +.P +While the two output formats are guaranteed to be functionally equivalent for +the given seccomp filter configuration, the filter instructions, and their +ordering, are not guaranteed to be the same in both the BPF and PFC formats. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +Return zero on success or one of the following error codes on +failure: +.TP +.B -ECANCELED +There was a system failure beyond the control of the library. +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.P +If the \fISCMP_FLTATR_API_SYSRAWRC\fP filter attribute is non-zero then +additional error codes may be returned to the caller; these additional error +codes are the negative \fIerrno\fP values returned by the system. Unfortunately +libseccomp can make no guarantees about these return values. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + int filter_fd; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + filter_fd = open("/tmp/seccomp_filter.bpf", O_WRONLY); + if (filter_fd == \-1) { + rc = \-errno; + goto out; + } + + rc = seccomp_export_bpf(ctx, filter_fd); + if (rc < 0) { + close(filter_fd); + goto out; + } + close(filter_fd); + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_release (3) + diff --git a/doc/man/man3/seccomp_export_pfc.3 b/doc/man/man3/seccomp_export_pfc.3 new file mode 100644 index 0000000..45c49a3 --- /dev/null +++ b/doc/man/man3/seccomp_export_pfc.3 @@ -0,0 +1 @@ +.so man3/seccomp_export_bpf.3 diff --git a/doc/man/man3/seccomp_init.3 b/doc/man/man3/seccomp_init.3 new file mode 100644 index 0000000..ca6224c --- /dev/null +++ b/doc/man/man3/seccomp_init.3 @@ -0,0 +1,166 @@ +.TH "seccomp_init" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_init, seccomp_reset \- Initialize the seccomp filter state +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "scmp_filter_ctx seccomp_init(uint32_t " def_action ");" +.BI "int seccomp_reset(scmp_filter_ctx " ctx ", uint32_t " def_action ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_init () +and +.BR seccomp_reset () +functions (re)initialize the internal seccomp filter state, prepares it for +use, and sets the default action based on the +.I def_action +parameter. The +.BR seccomp_init () +function must be called before any other libseccomp functions as the rest +of the library API will fail if the filter context is not initialized properly. +The +.BR seccomp_reset () +function releases the existing filter context state before reinitializing it +and can only be called after a call to +.BR seccomp_init () +has succeeded. If +.BR seccomp_reset () +is called with a NULL filter, it resets the library's global task state, +including any notification file descriptors retrieved by +.BR seccomp_notify_fd (3). +Normally this is not needed, but it may be required to continue using the +library after a +.BR fork () +or +.BR clone () +call to ensure the API level and user notification state is properly reset. +.P +When the caller is finished configuring the seccomp filter and has loaded it +into the kernel, the caller should call +.BR seccomp_release (3) +to release all of the filter context state. +.P +Valid +.I def_action +values are as follows: +.TP +.B SCMP_ACT_KILL +The thread will be terminated by the kernel with SIGSYS when it calls a syscall +that does not match any of the configured seccomp filter rules. The thread +will not be able to catch the signal. +.TP +.B SCMP_ACT_KILL_PROCESS +The entire process will be terminated by the kernel with SIGSYS when it calls a +syscall that does not match any of the configured seccomp filter rules. +.TP +.B SCMP_ACT_TRAP +The thread will be sent a SIGSYS signal when it calls a syscall that does not +match any of the configured seccomp filter rules. It may catch this and change +its behavior accordingly. When using SA_SIGINFO with +.BR sigaction (2), +si_code will be set to SYS_SECCOMP, si_syscall will be set to the syscall that +failed the rules, and si_arch will be set to the AUDIT_ARCH for the active ABI. +.TP +.B SCMP_ACT_ERRNO(uint16_t errno) +The thread will receive a return value of +.I errno +when it calls a syscall that does not match any of the configured seccomp filter +rules. +.TP +.B SCMP_ACT_TRACE(uint16_t msg_num) +If the thread is being traced and the tracing process specified the +.B PTRACE_O_TRACESECCOMP +option in the call to +.BR ptrace (2), +the tracing process will be notified, via +.BR PTRACE_EVENT_SECCOMP , +and the value provided in +.I msg_num +can be retrieved using the +.B PTRACE_GETEVENTMSG +option. +.TP +.B SCMP_ACT_LOG +The seccomp filter will have no effect on the thread calling the syscall if it +does not match any of the configured seccomp filter rules but the syscall will +be logged. +.TP +.B SCMP_ACT_ALLOW +The seccomp filter will have no effect on the thread calling the syscall if it +does not match any of the configured seccomp filter rules. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_init () +function returns a filter context on success, NULL on failure. The +.BR seccomp_reset () +function returns zero on success or one of the following error codes on +failure: +.TP +.B -EINVAL +Invalid input, either the context or action is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + rc = seccomp_reset(ctx, SCMP_ACT_KILL); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_release (3) diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3 new file mode 100644 index 0000000..729f73e --- /dev/null +++ b/doc/man/man3/seccomp_load.3 @@ -0,0 +1,112 @@ +.TH "seccomp_load" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_load \- Load the current seccomp filter into the kernel +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "int seccomp_load(scmp_filter_ctx " ctx ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +Loads the seccomp filter provided by +.I ctx +into the kernel; if the function +succeeds the new seccomp filter will be active when the function returns. +.P +As it is possible to have multiple stacked seccomp filters for a given task +(defined as either a process or a thread), it is important to remember that +each of the filters loaded for a given task are executed when a syscall is +made and the "strictest" rule is the rule that is applied. In the case of +seccomp, "strictest" is defined as the action with the lowest value (e.g. +.I SCMP_ACT_KILL +is "stricter" than +.IR SCMP_ACT_ALLOW ). +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +Returns zero on success or one of the following error codes on failure: +.TP +.B -ECANCELED +There was a system failure beyond the control of the library. +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.TP +.B -ESRCH +Unable to load the filter due to thread issues. +.P +If the \fISCMP_FLTATR_API_SYSRAWRC\fP filter attribute is non-zero then +additional error codes may be returned to the caller; these additional error +codes are the negative \fIerrno\fP values returned by the system. Unfortunately +libseccomp can make no guarantees about these return values. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + rc = seccomp_load(ctx); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_reset (3), +.BR seccomp_release (3), +.BR seccomp_rule_add (3), +.BR seccomp_rule_add_exact (3) + + diff --git a/doc/man/man3/seccomp_merge.3 b/doc/man/man3/seccomp_merge.3 new file mode 100644 index 0000000..10b3c3f --- /dev/null +++ b/doc/man/man3/seccomp_merge.3 @@ -0,0 +1,136 @@ +.TH "seccomp_merge" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_merge \- Merge two seccomp filters +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "int seccomp_merge(scmp_filter_ctx " dst ", scmp_filter_ctx " src ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_merge () +function merges the seccomp filter in +.I src +with the filter in +.I dst +and stores the resulting in the +.I dst +filter. If successful, the +.I src +seccomp filter is released and all internal memory associated with the filter +is freed; there is no need to call +.BR seccomp_release (3) +on +.I src +and the caller should discard any references to the filter. +.P +In order to merge two seccomp filters, both filters must have the same +attribute values and no overlapping architectures. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +Returns zero on success or one of the following error codes on +failure: +.TP +.B -EDOM +Unable to merge the filters due to architecture issues, e.g. byte endian +mismatches. +.TP +.B -EEXIST +The architecture already exists in the filter. +.TP +.B -EINVAL +One of the filters is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx_32, ctx_64; + + ctx_32 = seccomp_init(SCMP_ACT_KILL); + if (ctx_32 == NULL) + goto out_all; + ctx_64 = seccomp_init(SCMP_ACT_KILL); + if (ctx_64 == NULL) + goto out_all; + + if (seccomp_arch_exist(ctx_32, SCMP_ARCH_X86) == \-EEXIST) { + rc = seccomp_arch_add(ctx_32, SCMP_ARCH_X86); + if (rc != 0) + goto out_all; + rc = seccomp_arch_remove(ctx_32, SCMP_ARCH_NATIVE); + if (rc != 0) + goto out_all; + } + if (seccomp_arch_exist(ctx_64, SCMP_ARCH_X86_64) == \-EEXIST) { + rc = seccomp_arch_add(ctx_64, SCMP_ARCH_X86_64); + if (rc != 0) + goto out_all; + rc = seccomp_arch_remove(ctx_64, SCMP_ARCH_NATIVE); + if (rc != 0) + goto out_all; + } + + /* ... */ + + rc = seccomp_merge(ctx_64, ctx_32); + if (rc != 0) + goto out_all; + + /* NOTE: the 'ctx_32' filter is no longer valid at this point */ + + /* ... */ + +out: + seccomp_release(ctx_64); + return \-rc; +out_all: + seccomp_release(ctx_32); + goto out; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_reset (3), +.BR seccomp_arch_add (3), +.BR seccomp_arch_remove (3), +.BR seccomp_attr_get (3), +.BR seccomp_attr_set (3) diff --git a/doc/man/man3/seccomp_notify_alloc.3 b/doc/man/man3/seccomp_notify_alloc.3 new file mode 100644 index 0000000..cb1c048 --- /dev/null +++ b/doc/man/man3/seccomp_notify_alloc.3 @@ -0,0 +1,114 @@ +.TH "seccomp_notify_alloc" 3 "30 May 2020" "tycho@tycho.ws" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_notify_alloc, seccomp_notify_free, seccomp_notify_receive, +seccomp_notify_respond, seccomp_notify_id_valid, seccomp_notify_fd \- Manage seccomp notifications +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.BI "int seccomp_notify_alloc(struct seccomp_notif **" req ", struct seccomp_notif_resp **" resp ")" +.BI "void seccomp_notify_free(struct seccomp_notif *" req ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notify_receive(int " fd ", struct seccomp_notif *" req ")" +.BI "int seccomp_notify_respond(int " fd ", struct seccomp_notif_resp *" resp ")" +.BI "int seccomp_notify_id_valid(int " fd ", uint64_t " id ")" +.BI "int seccomp_notify_fd(const scmp_filter_ctx " ctx ")" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_notify_alloc () +function dynamically allocates enough memory for a seccomp notification and +response. Note that one should always use these functions and not depend on the +structure sizes in headers, since the size can vary depending on the kernel +version. This function takes care to ask the kernel how big each structure +should be, and allocates the right amount of memory. The +.BR seccomp_notify_free () +function frees memory allocated by +.BR seccomp_notify_alloc (). +.P +The +.BR seccomp_notify_receive () +function receives a notification from a seccomp notify fd (obtained from +.BR seccomp_notify_fd ()). +.P +The +.BR seccomp_notify_respond () +function sends a response to a particular notification. The id field should be +the same as the id from the request, so that the kernel knows which request +this response corresponds to. +.P +The +.BR seccomp_notify_id_valid () +function checks to see if the syscall from a particular notification request is +still valid, i.e. if the task is still alive. See NOTES below for details on +race conditions. +.P +The +.BR seccomp_notify_fd () +returns the notification fd of a filter after it has been loaded. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_notify_fd () +returns the notification fd of the loaded filter, -1 if a notification fd has +not yet been created, and -EINVAL if the filter context is invalid. +.P +The +.BR seccomp_notify_id_valid () +returns 0 if the id is valid, and -ENOENT if it is not. +.P +The +.BR seccomp_notify_alloc (), +.BR seccomp_notify_receive (), +and +.BR seccomp_notify_respond () +functions return zero on success, or one of the following error codes on +failure: +.TP +.B -ECANCELED +There was a system failure beyond the control of the library, check the +\fIerrno\fP value for more information. +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.TP +.B -EOPNOTSUPP +The library doesn't support the particular operation. +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +Care should be taken to avoid two different time of check/time of use errors. +First, after opening any resources relevant to the pid for a notification (e.g. +/proc/pid/mem for reading tracee memory to make policy decisions), applications +should call +.BR seccomp_notify_id_valid () +to make sure that the resources the application has opened correspond to the +right pid, i.e. that the pid didn't die and a different task take its place. +.P +Second, the classic time of check/time of use issue with seccomp memory should +also be avoided: applications should copy any memory they wish to use to make +decisions from the tracee into its own address space before applying any policy +decisions, since a multi-threaded tracee may edit the memory at any time, +including after it's used to make a policy decision. +.P +A complete example of how to avoid these two races is available in the Linux +Kernel source tree at +.BR /samples/seccomp/user-trap.c. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Tycho Andersen <tycho@tycho.ws> +.\" ////////////////////////////////////////////////////////////////////////// diff --git a/doc/man/man3/seccomp_notify_fd.3 b/doc/man/man3/seccomp_notify_fd.3 new file mode 100644 index 0000000..0c168c8 --- /dev/null +++ b/doc/man/man3/seccomp_notify_fd.3 @@ -0,0 +1 @@ +.so man3/seccomp_notify_alloc.3 diff --git a/doc/man/man3/seccomp_notify_free.3 b/doc/man/man3/seccomp_notify_free.3 new file mode 100644 index 0000000..0c168c8 --- /dev/null +++ b/doc/man/man3/seccomp_notify_free.3 @@ -0,0 +1 @@ +.so man3/seccomp_notify_alloc.3 diff --git a/doc/man/man3/seccomp_notify_id_valid.3 b/doc/man/man3/seccomp_notify_id_valid.3 new file mode 100644 index 0000000..0c168c8 --- /dev/null +++ b/doc/man/man3/seccomp_notify_id_valid.3 @@ -0,0 +1 @@ +.so man3/seccomp_notify_alloc.3 diff --git a/doc/man/man3/seccomp_notify_receive.3 b/doc/man/man3/seccomp_notify_receive.3 new file mode 100644 index 0000000..0c168c8 --- /dev/null +++ b/doc/man/man3/seccomp_notify_receive.3 @@ -0,0 +1 @@ +.so man3/seccomp_notify_alloc.3 diff --git a/doc/man/man3/seccomp_notify_respond.3 b/doc/man/man3/seccomp_notify_respond.3 new file mode 100644 index 0000000..0c168c8 --- /dev/null +++ b/doc/man/man3/seccomp_notify_respond.3 @@ -0,0 +1 @@ +.so man3/seccomp_notify_alloc.3 diff --git a/doc/man/man3/seccomp_release.3 b/doc/man/man3/seccomp_release.3 new file mode 100644 index 0000000..38733be --- /dev/null +++ b/doc/man/man3/seccomp_release.3 @@ -0,0 +1,77 @@ +.TH "seccomp_release" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_release \- Release the seccomp filter state +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "void seccomp_release(scmp_filter_ctx " ctx ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +Releases the seccomp filter in +.I ctx +which was first initialized by +.BR seccomp_init (3) +or +.BR seccomp_reset (3) +and frees any memory associated with the given seccomp filter context. +Any seccomp filters loaded into the kernel are not affected. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +Does not return a value. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + return 1; + + /* ... */ + + seccomp_release(ctx); + return 0; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_init (3), +.BR seccomp_reset (3) + + diff --git a/doc/man/man3/seccomp_reset.3 b/doc/man/man3/seccomp_reset.3 new file mode 100644 index 0000000..6f551cd --- /dev/null +++ b/doc/man/man3/seccomp_reset.3 @@ -0,0 +1 @@ +.so man3/seccomp_init.3 diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3 new file mode 100644 index 0000000..3022699 --- /dev/null +++ b/doc/man/man3/seccomp_rule_add.3 @@ -0,0 +1,460 @@ +.TH "seccomp_rule_add" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "int SCMP_SYS(" syscall_name ");" +.sp +.BI "struct scmp_arg_cmp SCMP_CMP(unsigned int " arg "," +.BI " enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A0(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A1(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A2(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A3(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A4(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A5(enum scmp_compare " op ", " ... ");" +.sp +.BI "struct scmp_arg_cmp SCMP_CMP64(unsigned int " arg "," +.BI " enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A0_64(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A1_64(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A2_64(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A3_64(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A4_64(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A5_64(enum scmp_compare " op ", " ... ");" +.sp +.BI "struct scmp_arg_cmp SCMP_CMP32(unsigned int " arg "," +.BI " enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A0_32(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A1_32(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A2_32(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A3_32(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A4_32(enum scmp_compare " op ", " ... ");" +.BI "struct scmp_arg_cmp SCMP_A5_32(enum scmp_compare " op ", " ... ");" +.sp +.BI "int seccomp_rule_add(scmp_filter_ctx " ctx ", uint32_t " action "," +.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");" +.BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action "," +.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");" +.sp +.BI "int seccomp_rule_add_array(scmp_filter_ctx " ctx "," +.BI " uint32_t " action ", int " syscall "," +.BI " unsigned int " arg_cnt "," +.BI " const struct scmp_arg_cmp *"arg_array ");" +.BI "int seccomp_rule_add_exact_array(scmp_filter_ctx " ctx "," +.BI " uint32_t " action ", int " syscall "," +.BI " unsigned int " arg_cnt "," +.BI " const struct scmp_arg_cmp *"arg_array ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_rule_add (), +.BR seccomp_rule_add_array (), +.BR seccomp_rule_add_exact (), +and +.BR seccomp_rule_add_exact_array () +functions all add a new filter rule to the current seccomp filter. The +.BR seccomp_rule_add () +and +.BR seccomp_rule_add_array () +functions will make a "best effort" to add the rule as specified, but may alter +the rule slightly due to architecture specifics (e.g. internal rewriting of +multiplexed syscalls, like socket and ipc functions on x86). The +.BR seccomp_rule_add_exact () +and +.BR seccomp_rule_add_exact_array () +functions will attempt to add the rule exactly as specified so it may behave +differently on different architectures. While it does not guarantee a exact +filter ruleset, +.BR seccomp_rule_add () +and +.BR seccomp_rule_add_array () +do guarantee the same behavior regardless of the architecture. +.P +The newly added filter rule does not take effect until the entire filter is +loaded into the kernel using +.BR seccomp_load (3). +When adding rules to a filter, it is important to consider the impact of +previously loaded filters; see the +.BR seccomp_load (3) +documentation for more information. +.P +All of the filter rules supplied by the calling application are combined into +a union, with additional logic to eliminate redundant syscall filters. For +example, if a rule is added which allows a given syscall with a specific set of +argument values and later a rule is added which allows the same syscall +regardless the argument values then the first, more specific rule, is +effectively dropped from the filter by the second more generic rule. +.P +The +.BR SCMP_CMP (), +.BR SCMP_CMP64 (), +.BR SCMP_A{0-5} (), +and +.BR SCMP_A{0-5}_64 () +macros generate a scmp_arg_cmp structure for use with the above functions. The +.BR SCMP_CMP () +and +.BR SCMP_CMP64 () +macros allows the caller to specify an arbitrary argument along with the +comparison operator, 64-bit mask, and 64-bit datum values where the +.BR SCMP_A{0-5} () +and +.BR SCMP_A{0-5}_64 () +macros are specific to a certain argument. +.P +The +.BR SCMP_CMP32 () +and +.BR SCMP_A{0-5}_32 () +macros are similar to the variants above, but they take 32-bit mask and 32-bit +datum values. +.P +It is recommended that whenever possible developers avoid using the +.BR SCMP_CMP () +and +.BR SCMP_A{0-5} () +macros and use the variants which are explicitly 32 or 64-bit. This should +help eliminate problems caused by an unwanted sign extension of negative datum +values. +.P +If syscall argument comparisons are included in the filter rule, all of the +comparisons must be true for the rule to match. +.P +When adding syscall argument comparisons to the filter it is important to +remember that while it is possible to have multiple comparisons in a single +rule, you can only compare each argument once in a single rule. In other words, +you can not have multiple comparisons of the 3rd syscall argument in a single +rule. +.P +In a filter containing multiple architectures, it is an error to add a filter +rule for a syscall that does not exist in all of the filter's architectures. +.P +While it is possible to specify the +.I syscall +value directly using the standard +.B __NR_syscall +values, in order to ensure proper operation across multiple architectures it +is highly recommended to use the +.BR SCMP_SYS () +macro instead. See the EXAMPLES section below. It is also important to +remember that regardless of the architectures present in the filter, the +syscall numbers used in filter rules are interpreted in the context of the +native architecture. +.P +Starting with Linux v4.8, there may be a need to create a rule with a syscall +value of -1 to allow tracing programs to skip a syscall invocation; in order +to create a rule with a -1 syscall value it is necessary to first set the +.B SCMP_FLTATR_API_TSKIP +attribute. See +.BR seccomp_attr_set (3) +for more information. +.P +The filter context +.I ctx +is the value returned by the call to +.BR seccomp_init (3). +.P +Valid +.I action +values are as follows: +.TP +.B SCMP_ACT_KILL +The thread will be killed by the kernel when it calls a syscall that matches +the filter rule. +.TP +.B SCMP_ACT_KILL_PROCESS +The process will be killed by the kernel when it calls a syscall that matches +the filter rule. +.TP +.B SCMP_ACT_TRAP +The thread will throw a SIGSYS signal when it calls a syscall that matches the +filter rule. +.TP +.B SCMP_ACT_ERRNO(uint16_t errno) +The thread will receive a return value of +.I errno +when it calls a syscall that matches the filter rule. +.TP +.B SCMP_ACT_TRACE(uint16_t msg_num) +If the thread is being traced and the tracing process specified the +.B PTRACE_O_TRACESECCOMP +option in the call to +.BR ptrace (2), +the tracing process will be notified, via +.B PTRACE_EVENT_SECCOMP +, and the value provided in +.I msg_num +can be retrieved using the +.B PTRACE_GETEVENTMSG +option. +.TP +.B SCMP_ACT_LOG +The seccomp filter will have no effect on the thread calling the syscall if it +matches the filter rule but the syscall will be logged. +.TP +.B SCMP_ACT_ALLOW +The seccomp filter will have no effect on the thread calling the syscall if it +matches the filter rule. +.TP +.B SCMP_ACT_NOTIFY +A monitoring process will be notified when a process running the seccomp +filter calls a syscall that matches the filter rule. The process that invokes +the syscall waits in the kernel until the monitoring process has responded via +.B seccomp_notify_respond (3) +\&. + +When a filter utilizing +.B SCMP_ACT_NOTIFY +is loaded into the kernel, the kernel generates a notification fd that must be +used to communicate between the monitoring process and the process(es) being +filtered. See +.B seccomp_notif_fd (3) +for more information. + +.P +Valid comparison +.I op +values are as follows: +.TP +.B SCMP_CMP_NE +Matches when the argument value is not equal to the datum value, example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_NE , +.I datum +) +.TP +.B SCMP_CMP_LT +Matches when the argument value is less than the datum value, example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_LT , +.I datum +) +.TP +.B SCMP_CMP_LE +Matches when the argument value is less than or equal to the datum value, +example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_LE , +.I datum +) +.TP +.B SCMP_CMP_EQ +Matches when the argument value is equal to the datum value, example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_EQ , +.I datum +) +.TP +.B SCMP_CMP_GE +Matches when the argument value is greater than or equal to the datum value, +example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_GE , +.I datum +) +.TP +.B SCMP_CMP_GT +Matches when the argument value is greater than the datum value, example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_GT , +.I datum +) +.TP +.B SCMP_CMP_MASKED_EQ +Matches when the masked argument value is equal to the masked datum value, +example: +.sp +SCMP_CMP( +.I arg +, SCMP_CMP_MASKED_EQ , +.I mask +, +.I datum +) +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR SCMP_SYS () +macro returns a value suitable for use as the +.I syscall +value in the +.BR seccomp_rule_add* () +functions. In a similar manner, the +.BR SCMP_CMP () +and +.BR SCMP_A* () +macros return values suitable for use as argument comparisons in the +.BR seccomp_rule_add () +and +.BR seccomp_rule_add_exact () +functions. +.P +The +.BR seccomp_rule_add (), +.BR seccomp_rule_add_array (), +.BR seccomp_rule_add_exact (), +and +.BR seccomp_rule_add_exact_array () +functions return zero on success or one of the following error codes on +failure: +.TP +.B -EDOM +Architecture specific failure. +.TP +.B -EEXIST +The rule already exists. +.TP +.B -EACCCES +The rule conflicts with the filter (for example, the rule +.I action +equals the default action of the filter). +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.TP +.B -EOPNOTSUPP +The library doesn't support the particular operation. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <fcntl.h> +#include <seccomp.h> +#include <sys/stat.h> +#include <sys/types.h> +#include <stddef.h> + +#define BUF_SIZE 256 + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) }; + int fd; + unsigned char buf[BUF_SIZE]; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + fd = open("file.txt", 0); + + /* ... */ + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0); + if (rc < 0) + goto out; + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit_group), 0); + if (rc < 0) + goto out; + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(exit), 0); + if (rc < 0) + goto out; + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3, + SCMP_A0(SCMP_CMP_EQ, fd), + SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf), + SCMP_A2(SCMP_CMP_LE, BUF_SIZE)); + if (rc < 0) + goto out; + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1, + SCMP_CMP(0, SCMP_CMP_EQ, fd)); + if (rc < 0) + goto out; + + rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1, + arg_cmp); + if (rc < 0) + goto out; + + rc = seccomp_load(ctx); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH BUGS +.\" ////////////////////////////////////////////////////////////////////////// +.P +The runtime behavior of seccomp filters is dependent upon the kernel +version, the processor architecture, and other libraries including libc. +This could affect the return code of a seccomp filter. + +.TP +.B * +PowerPC glibc will not return a negative number when the +.B getpid() +syscall is invoked. If a seccomp filter has been created where +.B getpid() +will return a negative number from the kernel, then PowerPC glibc will +return the absolute value of the errno. In this case, it is very difficult +for an application to distinguish between the errno and a valid pid. + +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_syscall_resolve_name_rewrite (3), +.BR seccomp_syscall_priority (3), +.BR seccomp_load (3), +.BR seccomp_attr_set (3) diff --git a/doc/man/man3/seccomp_rule_add_array.3 b/doc/man/man3/seccomp_rule_add_array.3 new file mode 100644 index 0000000..53714e7 --- /dev/null +++ b/doc/man/man3/seccomp_rule_add_array.3 @@ -0,0 +1 @@ +.so man3/seccomp_rule_add.3 diff --git a/doc/man/man3/seccomp_rule_add_exact.3 b/doc/man/man3/seccomp_rule_add_exact.3 new file mode 100644 index 0000000..53714e7 --- /dev/null +++ b/doc/man/man3/seccomp_rule_add_exact.3 @@ -0,0 +1 @@ +.so man3/seccomp_rule_add.3 diff --git a/doc/man/man3/seccomp_rule_add_exact_array.3 b/doc/man/man3/seccomp_rule_add_exact_array.3 new file mode 100644 index 0000000..53714e7 --- /dev/null +++ b/doc/man/man3/seccomp_rule_add_exact_array.3 @@ -0,0 +1 @@ +.so man3/seccomp_rule_add.3 diff --git a/doc/man/man3/seccomp_syscall_priority.3 b/doc/man/man3/seccomp_syscall_priority.3 new file mode 100644 index 0000000..5621b85 --- /dev/null +++ b/doc/man/man3/seccomp_syscall_priority.3 @@ -0,0 +1,126 @@ +.TH "seccomp_syscall_priority" 3 "30 May 2020" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_syscall_priority \- Prioritize syscalls in the seccomp filter +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B typedef void * scmp_filter_ctx; +.sp +.BI "int SCMP_SYS(" syscall_name ");" +.sp +.BI "int seccomp_syscall_priority(scmp_filter_ctx " ctx "," +.BI " int " syscall ", uint8_t " priority ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_syscall_priority () +function provides a priority hint to the seccomp filter generator in libseccomp +such that higher priority syscalls are placed earlier in the seccomp filter code +so that they incur less overhead at the expense of lower priority syscalls. A +syscall's priority can be set regardless of if any rules currently exist for +that syscall; the library will remember the priority and it will be assigned to +the syscall if and when a rule for that syscall is created. +.P +While it is possible to specify the +.I syscall +value directly using the standard +.B __NR_syscall +values, in order to ensure proper operation across multiple architectures it +is highly recommended to use the +.BR SCMP_SYS () +macro instead. See the EXAMPLES section below. +.P +The +.I priority +parameter takes an 8-bit value ranging from 0 \- 255; a higher value represents +a higher priority. +.P +The filter context +.I ctx +is the value returned by the call to +.BR seccomp_init (). +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR SCMP_SYS () +macro returns a value suitable for use as the +.I syscall +value in +.BR seccomp_syscall_priority (). +.P +The +.BR seccomp_syscall_priority () +function returns zero on success or one of the following error codes on +failure: +.TP +.B -EDOM +Architecture specific failure. +.TP +.B -EFAULT +Internal libseccomp failure. +.TP +.B -EINVAL +Invalid input, either the context or architecture token is invalid. +.TP +.B -ENOMEM +The library was unable to allocate enough memory. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + rc = seccomp_syscall_priority(ctx, SCMP_SYS(read), 200); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_rule_add (3), +.BR seccomp_rule_add_exact (3) diff --git a/doc/man/man3/seccomp_syscall_resolve_name.3 b/doc/man/man3/seccomp_syscall_resolve_name.3 new file mode 100644 index 0000000..3c0f789 --- /dev/null +++ b/doc/man/man3/seccomp_syscall_resolve_name.3 @@ -0,0 +1,133 @@ +.TH "seccomp_syscall_resolve_name" 3 "8 May 2014" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_syscall_resolve_name \- Resolve a syscall name +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.BI "int seccomp_syscall_resolve_name(const char *" name ");" +.BI "int seccomp_syscall_resolve_name_arch(uint32_t " arch_token "," +.BI " const char *" name ");" +.BI "int seccomp_syscall_resolve_name_rewrite(uint32_t " arch_token "," +.BI " const char *" name ");" +.BI "char *seccomp_syscall_resolve_num_arch(uint32_t " arch_token ", int " num ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_syscall_resolve_name() , +.BR seccomp_syscall_resolve_name_arch() , +and +.BR seccomp_syscall_resolve_name_rewrite() +functions resolve the commonly used syscall name to the syscall number used by +the kernel and the rest of the libseccomp API, with +.BR seccomp_syscall_resolve_name_rewrite() +rewriting the syscall number for architectures that modify the syscall. Syscall +rewriting typically happens in case of a multiplexed syscall, like +.BR socketcall (2) +or +.BR ipc (2) +on x86. +.BR seccomp_syscall_resolve_num_arch() +function resolves the syscall number used by the kernel to the commonly used +syscall name. +.P +The caller is responsible for freeing the returned string from +.BR seccomp_syscall_resolve_num_arch() . +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +.P +In the case of +.BR seccomp_syscall_resolve_name() , +.BR seccomp_syscall_resolve_name_arch() , +and +.BR seccomp_syscall_resolve_name_rewrite() +the associated syscall number is returned, with the negative pseudo syscall +number being returned in cases where the given syscall does not exist for the +architecture. The value +.BR __NR_SCMP_ERROR +is returned in case of error. In all cases, the return value is suitable for +use in any libseccomp API function which requires the syscall number, examples include +.BR seccomp_rule_add () +and +.BR seccomp_rule_add_exact (). +.P +In the case of +.BR seccomp_syscall_resolve_num_arch() +the associated syscall name is returned and it remains the callers +responsibility to free the returned string via +.BR free (3). +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + int rc = \-1; + scmp_filter_ctx ctx; + + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; + + /* ... */ + + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, + seccomp_syscall_resolve_name("open"), 0); + if (rc < 0) + goto out; + + /* ... */ + + rc = seccomp_load(ctx); + if (rc < 0) + goto out; + + /* ... */ + +out: + seccomp_release(ctx); + return \-rc; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +In case of bare syscalls implemented on top of a multiplexed syscall, +.BR seccomp_syscall_resolve_name() +and +.BR seccomp_syscall_resolve_name_arch() +can be used to verify if a bare syscall is implemented for a specific +architecture, while +.BR seccomp_syscall_resolve_name_rewrite() +can be used to determine the underlying multiplexed syscall. +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// +.SH SEE ALSO +.\" ////////////////////////////////////////////////////////////////////////// +.BR seccomp_rule_add (3), +.BR seccomp_rule_add_exact (3) diff --git a/doc/man/man3/seccomp_syscall_resolve_name_arch.3 b/doc/man/man3/seccomp_syscall_resolve_name_arch.3 new file mode 100644 index 0000000..f6d4472 --- /dev/null +++ b/doc/man/man3/seccomp_syscall_resolve_name_arch.3 @@ -0,0 +1 @@ +.so man3/seccomp_syscall_resolve_name.3 diff --git a/doc/man/man3/seccomp_syscall_resolve_name_rewrite.3 b/doc/man/man3/seccomp_syscall_resolve_name_rewrite.3 new file mode 100644 index 0000000..f6d4472 --- /dev/null +++ b/doc/man/man3/seccomp_syscall_resolve_name_rewrite.3 @@ -0,0 +1 @@ +.so man3/seccomp_syscall_resolve_name.3 diff --git a/doc/man/man3/seccomp_syscall_resolve_num_arch.3 b/doc/man/man3/seccomp_syscall_resolve_num_arch.3 new file mode 100644 index 0000000..f6d4472 --- /dev/null +++ b/doc/man/man3/seccomp_syscall_resolve_num_arch.3 @@ -0,0 +1 @@ +.so man3/seccomp_syscall_resolve_name.3 diff --git a/doc/man/man3/seccomp_version.3 b/doc/man/man3/seccomp_version.3 new file mode 100644 index 0000000..bce4349 --- /dev/null +++ b/doc/man/man3/seccomp_version.3 @@ -0,0 +1,87 @@ +.TH "seccomp_version" 3 "18 February 2016" "paul@paul-moore.com" "libseccomp Documentation" +.\" ////////////////////////////////////////////////////////////////////////// +.SH NAME +.\" ////////////////////////////////////////////////////////////////////////// +seccomp_version \- Query the libseccomp version information +.\" ////////////////////////////////////////////////////////////////////////// +.SH SYNOPSIS +.\" ////////////////////////////////////////////////////////////////////////// +.nf +.B #include <seccomp.h> +.sp +.B struct scmp_version { +.B unsigned int major; +.B unsigned int minor; +.B unsigned int micro; +.B } +.sp +.BI "const struct scmp_version *seccomp_version(" void ");" +.sp +Link with \fI\-lseccomp\fP. +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH DESCRIPTION +.\" ////////////////////////////////////////////////////////////////////////// +.P +The +.BR seccomp_version () +and +.BR seccomp_reset () +functions return a pointer to a +.B scmp_version +struct which contains the version information of the currently loaded +libseccomp library. This function can be used by applications that need to +verify that they are linked to a specific libseccomp version at runtime. +.P +The caller should not attempt to free the returned +.B scmp_version +struct when finished. +.\" ////////////////////////////////////////////////////////////////////////// +.SH RETURN VALUE +.\" ////////////////////////////////////////////////////////////////////////// +The +.BR seccomp_version () +function returns a pointer to a +.B scmp_version +structure on success, NULL on failure. The caller should not attempt to free +the returned structure. +.\" ////////////////////////////////////////////////////////////////////////// +.SH EXAMPLES +.\" ////////////////////////////////////////////////////////////////////////// +.nf +#include <seccomp.h> + +int main(int argc, char *argv[]) +{ + const struct scmp_version *ver; + + ver = seccomp_version(); + if (ver == NULL) + goto err; + + /* ... */ + + return 0; + +err: + return 1; +} +.fi +.\" ////////////////////////////////////////////////////////////////////////// +.SH NOTES +.\" ////////////////////////////////////////////////////////////////////////// +.P +While the seccomp filter can be generated independent of the kernel, kernel +support is required to load and enforce the seccomp filter generated by +libseccomp. +.P +The libseccomp project site, with more information and the source code +repository, can be found at https://github.com/seccomp/libseccomp. This tool, +as well as the libseccomp library, is currently under development, please +report any bugs at the project site or directly to the author. +.\" ////////////////////////////////////////////////////////////////////////// +.SH AUTHOR +.\" ////////////////////////////////////////////////////////////////////////// +Paul Moore <paul@paul-moore.com> +.\" ////////////////////////////////////////////////////////////////////////// + |