Signed-off-by: Paul Moore <[email protected]> --- doc/man/man3/seccomp_attr_set.3 | 33 ++++++++++++++++++---------- doc/man/man3/seccomp_export_bpf.3 | 24 +++++++++++++------- doc/man/man3/seccomp_init.3 | 37 ++++++++++++++++++------------- doc/man/man3/seccomp_load.3 | 23 ++++++++++++------- doc/man/man3/seccomp_release.3 | 21 +++++++++++------- doc/man/man3/seccomp_rule_add.3 | 30 ++++++++++++++++--------- doc/man/man3/seccomp_syscall_priority.3 | 23 +++++++++++++------ 7 files changed, 121 insertions(+), 70 deletions(-)
diff --git a/doc/man/man3/seccomp_attr_set.3 b/doc/man/man3/seccomp_attr_set.3 index 3cbd513..d024227 100644 --- a/doc/man/man3/seccomp_attr_set.3 +++ b/doc/man/man3/seccomp_attr_set.3 @@ -1,4 +1,4 @@ -.TH "seccomp_attr_set" 3 "16 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_attr_set" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,10 +9,13 @@ seccomp_attr_set, seccomp_attr_get \- Manage the seccomp filter attributes .nf .B #include <seccomp.h> .sp +.B typedef void * scmp_filter_ctx; .B enum scmp_filter_attr; .sp -.BI "int seccomp_attr_set(enum scmp_filter_attr " attr ", uint32_t " value ");" -.BI "int seccomp_attr_get(enum scmp_filter_attr " attr ", uint32_t *" value ");" +.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 ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION @@ -26,9 +29,14 @@ 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_filter_init () +.BR seccomp_filter_init (3) or -.BR seccomp_filter_reset (). +.BR seccomp_filter_reset (3). +.P +The filter context +.I ctx +is the value returned by the call to +.BR seccomp_init (3). .P Valid .I attr @@ -36,9 +44,9 @@ values are as follows: .TP .B SCMP_FLTATR_ACT_DEFAULT The default filter action as specified in the call to -.BR seccomp_filter_init () +.BR seccomp_filter_init (3) or -.BR seccomp_filter_reset (). +.BR seccomp_filter_reset (3). This attribute is read-only. .TP .B SCMP_FLTATR_ACT_BADARCH @@ -67,22 +75,23 @@ Returns zero on success, negative errno values on failure. int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; - rc = seccomp_init(SCMP_ACT_ALLOW); - if (rc < 0) + ctx = seccomp_init(SCMP_ACT_ALLOW); + if (ctx == NULL) goto out; /* ... */ - rc = seccomp_attr_set(SCMP_FLTATR_ACT_BADARCH, SCMP_ACT_TRAP); + rc = seccomp_attr_set(ctx, SCMP_FLTATR_ACT_BADARCH, SCMP_ACT_TRAP); if (rc < 0) goto out; /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi diff --git a/doc/man/man3/seccomp_export_bpf.3 b/doc/man/man3/seccomp_export_bpf.3 index 33b5344..926b638 100644 --- a/doc/man/man3/seccomp_export_bpf.3 +++ b/doc/man/man3/seccomp_export_bpf.3 @@ -1,4 +1,4 @@ -.TH "seccomp_export_bpf" 3 "15 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_export_bpf" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,8 +9,10 @@ seccomp_export_bpf, seccomp_export_pfc \- Export the seccomp filter .nf .B #include <seccomp.h> .sp -.BI "int seccomp_export_bpf(int " fd ");" -.BI "int seccomp_export_pfc(int " fd ");" +.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 ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION @@ -30,6 +32,11 @@ 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. @@ -45,11 +52,12 @@ Returns zero on success, negative errno values on failure. int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; int filter_fd; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) goto out; /* ... */ @@ -60,7 +68,7 @@ int main(int argc, char *argv[]) goto out; } - rc = seccomp_export_bpf(filter_fd); + rc = seccomp_export_bpf(ctx, filter_fd); if (rc < 0) { close(filter_fd); goto out; @@ -70,7 +78,7 @@ int main(int argc, char *argv[]) /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi diff --git a/doc/man/man3/seccomp_init.3 b/doc/man/man3/seccomp_init.3 index 69a6800..067c042 100644 --- a/doc/man/man3/seccomp_init.3 +++ b/doc/man/man3/seccomp_init.3 @@ -1,4 +1,4 @@ -.TH "seccomp_init" 3 "5 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_init" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,8 +9,10 @@ seccomp_init, seccomp_reset \- Initialize the seccomp filter state .nf .B #include <seccomp.h> .sp -.BI "int seccomp_init(uint32_t " def_action ");" -.BI "int seccomp_reset(uint32_t " def_action ");" +.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 ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION @@ -20,24 +22,24 @@ The .BR seccomp_init () and .BR seccomp_reset () -functions initialize the internal seccomp filter state, prepares it for use, and -sets the default action based on the +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 state is not initialized properly. +of the library API will fail if the filter context is not initialized properly. The .BR seccomp_reset () -function releases the existing filter state before reinitializing it and can -only be called after a call to +function releases the existing filter context state before reinitializing it +and can only be called after a call to .BR seccomp_init () has succeeded. .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 internal filter state. +to release all of the filter context state. .P Valid .I def_action @@ -76,7 +78,11 @@ does not match any of the configured seccomp filter rules. .\" ////////////////////////////////////////////////////////////////////////// .SH RETURN VALUE .\" ////////////////////////////////////////////////////////////////////////// -Returns zero on success, negative errno values on failure. +The +.BR seccomp_init () +function returns a filter context on success, NULL on failure. The +.BR seccomp_reset () +function returns zero on success, negative errno values on failure. .\" ////////////////////////////////////////////////////////////////////////// .SH EXAMPLES .\" ////////////////////////////////////////////////////////////////////////// @@ -85,22 +91,23 @@ Returns zero on success, negative errno values on failure. int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) goto out; /* ... */ - rc = seccomp_reset(SCMP_ACT_KILL); + rc = seccomp_reset(ctx, SCMP_ACT_KILL); if (rc < 0) goto out; /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi diff --git a/doc/man/man3/seccomp_load.3 b/doc/man/man3/seccomp_load.3 index 8a88ba3..78944a2 100644 --- a/doc/man/man3/seccomp_load.3 +++ b/doc/man/man3/seccomp_load.3 @@ -1,4 +1,4 @@ -.TH "seccomp_load" 3 "5 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_load" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,13 +9,17 @@ seccomp_load \- Load the current seccomp filter into the kernel .nf .B #include <seccomp.h> .sp -.BI "int seccomp_load(void);" +.B typedef void * scmp_filter_ctx; +.sp +.BI "int seccomp_load(scmp_filter_ctx " ctx ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION .\" ////////////////////////////////////////////////////////////////////////// .P -Loads the currently configured seccomp filter into the kernel; if the function +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. .\" ////////////////////////////////////////////////////////////////////////// .SH RETURN VALUE @@ -29,22 +33,23 @@ Returns zero on success, negative errno values on failure. int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) - return -rc; + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + goto out; /* ... */ - rc = seccomp_load(); + rc = seccomp_load(ctx); if (rc < 0) goto out; /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi diff --git a/doc/man/man3/seccomp_release.3 b/doc/man/man3/seccomp_release.3 index 749770d..08a0a0b 100644 --- a/doc/man/man3/seccomp_release.3 +++ b/doc/man/man3/seccomp_release.3 @@ -1,4 +1,4 @@ -.TH "seccomp_release" 3 "5 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_release" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,17 +9,21 @@ seccomp_release \- Release the seccomp filter state .nf .B #include <seccomp.h> .sp -.BI "void seccomp_release(void);" +.B typedef void * scmp_filter_ctx; +.sp +.BI "void seccomp_release(scmp_filter_ctx " ctx ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION .\" ////////////////////////////////////////////////////////////////////////// .P -Releases the internal seccomp filter state initialized by +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 currently configured seccomp filter. +and frees any memory associated with the given seccomp filter context. Any seccomp filters loaded into the kernel are not affected. .\" ////////////////////////////////////////////////////////////////////////// .SH RETURN VALUE @@ -34,14 +38,15 @@ Does not return a value. int main(int argc, char *argv[]) { int rc; + scmp_filter_ctx ctx; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) - return -rc; + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) + return -1; /* ... */ - seccomp_release(); + seccomp_release(ctx); return 0; } .fi diff --git a/doc/man/man3/seccomp_rule_add.3 b/doc/man/man3/seccomp_rule_add.3 index 7de90b3..77c64a0 100644 --- a/doc/man/man3/seccomp_rule_add.3 +++ b/doc/man/man3/seccomp_rule_add.3 @@ -1,4 +1,4 @@ -.TH "seccomp_rule_add" 3 "5 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_rule_add" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,6 +9,8 @@ seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule .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 "," @@ -20,9 +22,9 @@ seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule .BI "struct scmp_arg_cmp SCMP_A4(enum scmp_compare " op ", " ... ");" .BI "struct scmp_arg_cmp SCMP_A5(enum scmp_compare " op ", " ... ");" .sp -.BI "int seccomp_rule_add(uint32_t " action "," +.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(uint32_t " action "," +.BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action "," .BI " int " syscall ", unsigned int " arg_cnt ", " ... ");" .fi .\" ////////////////////////////////////////////////////////////////////////// @@ -73,6 +75,11 @@ is highly recommended to use the .BR SCMP_SYS () macro instead. See the EXAMPLES section below. .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: @@ -200,12 +207,13 @@ functions return zero on success, negative errno values on failure. int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; int fd; unsigned char buf[BUF_SIZE]; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) goto out; /* ... */ @@ -214,30 +222,30 @@ int main(int argc, char *argv[]) /* ... */ - rc = seccomp_rule_add(SCMP_ACT_ALLOW, SCMP_SYS(close), 0); + rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0); if (rc < 0) goto out; - rc = seccomp_rule_add(SCMP_ACT_ALLOW, SCMP_SYS(read), 3, + 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(SCMP_ACT_ALLOW, SCMP_SYS(write), 1, + 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_load(); + rc = seccomp_load(ctx); if (rc < 0) goto out; /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi diff --git a/doc/man/man3/seccomp_syscall_priority.3 b/doc/man/man3/seccomp_syscall_priority.3 index 4337484..eb86069 100644 --- a/doc/man/man3/seccomp_syscall_priority.3 +++ b/doc/man/man3/seccomp_syscall_priority.3 @@ -1,4 +1,4 @@ -.TH "seccomp_syscall_priority" 3 "5 April 2012" "[email protected]" "libseccomp Documentation" +.TH "seccomp_syscall_priority" 3 "25 July 2012" "[email protected]" "libseccomp Documentation" .\" ////////////////////////////////////////////////////////////////////////// .SH NAME .\" ////////////////////////////////////////////////////////////////////////// @@ -9,9 +9,12 @@ seccomp_syscall_priority \- Prioritize syscalls in the seccomp filter .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(int " syscall ", uint8_t " priority ");" +.BI "int seccomp_syscall_priority(scmp_filter_ctx " ctx "," +.BI " int " syscall ", uint8_t " priority ");" .fi .\" ////////////////////////////////////////////////////////////////////////// .SH DESCRIPTION @@ -39,6 +42,11 @@ 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 .\" ////////////////////////////////////////////////////////////////////////// @@ -58,22 +66,23 @@ value in int main(int argc, char *argv[]) { - int rc; + int rc = -1; + scmp_filter_ctx ctx; - rc = seccomp_init(SCMP_ACT_KILL); - if (rc < 0) + ctx = seccomp_init(SCMP_ACT_KILL); + if (ctx == NULL) goto out; /* ... */ - rc = seccomp_syscall_priority(SCMP_SYS(read), 200); + rc = seccomp_syscall_priority(ctx, SCMP_SYS(read), 200); if (rc < 0) goto out; /* ... */ out: - seccomp_release(); + seccomp_release(ctx); return -rc; } .fi ------------------------------------------------------------------------------ Live Security Virtual Conference Exclusive live event will cover all the ways today's security and threat landscape has changed and how IT managers can respond. Discussions will include endpoint security, mobile security and the latest in malware threats. http://www.accelacomm.com/jaw/sfrnl04242012/114/50122263/ _______________________________________________ libseccomp-discuss mailing list [email protected] https://lists.sourceforge.net/lists/listinfo/libseccomp-discuss
