[linux-seccomp.git] / libseccomp / doc / man / man3 / seccomp_rule_add.3

.TH "seccomp_rule_add" 3 "25 July 2012" "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 "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. 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).
.P
The
.BR SCMP_CMP ()
and
.BR SCMP_A{0-5} ()
macros generate a scmp_arg_cmp structure for use with the above functions. The
.BR SCMP_CMP ()
macro allows the caller to specify an arbitrary argument along with the
comparison operator, mask, and datum values where the
.BR SCMP_A{0-5} ()
macros are specific to a certain argument.  See the EXAMPLES section below.
.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 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 does not
match any of the configured seccomp filter rules.
.TP
.B SCMP_ACT_TRAP
The thread will throw a SIGSYS signal when it calls a syscall that does not
match any of the configured seccomp filter rules.
.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
.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_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.
.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 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, negative errno values on failure.
.\" //////////////////////////////////////////////////////////////////////////
.SH EXAMPLES
.\" //////////////////////////////////////////////////////////////////////////
.nf
#include <fcntl.h>
#include <seccomp.h>
#include <sys/stat.h>
#include <sys/types.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(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 AUTHOR
.\" //////////////////////////////////////////////////////////////////////////
Paul Moore <paul@paul-moore.com>
.\" //////////////////////////////////////////////////////////////////////////
.SH SEE ALSO
.\" //////////////////////////////////////////////////////////////////////////
.BR seccomp_syscall_priority (3),
.BR seccomp_load (3)
Commit	Line	Data
8befd5cc MG	1	.TH "seccomp_rule_add" 3 "25 July 2012" "paul@paul-moore.com" "libseccomp Documentation"
	2	.\" //////////////////////////////////////////////////////////////////////////
	3	.SH NAME
	4	.\" //////////////////////////////////////////////////////////////////////////
	5	seccomp_rule_add, seccomp_rule_add_exact \- Add a seccomp filter rule
	6	.\" //////////////////////////////////////////////////////////////////////////
	7	.SH SYNOPSIS
	8	.\" //////////////////////////////////////////////////////////////////////////
	9	.nf
	10	.B #include <seccomp.h>
	11	.sp
	12	.B typedef void * scmp_filter_ctx;
	13	.sp
	14	.BI "int SCMP_SYS(" syscall_name ");"
	15	.sp
	16	.BI "struct scmp_arg_cmp SCMP_CMP(unsigned int " arg ","
	17	.BI " enum scmp_compare " op ", " ... ");"
	18	.BI "struct scmp_arg_cmp SCMP_A0(enum scmp_compare " op ", " ... ");"
	19	.BI "struct scmp_arg_cmp SCMP_A1(enum scmp_compare " op ", " ... ");"
	20	.BI "struct scmp_arg_cmp SCMP_A2(enum scmp_compare " op ", " ... ");"
	21	.BI "struct scmp_arg_cmp SCMP_A3(enum scmp_compare " op ", " ... ");"
	22	.BI "struct scmp_arg_cmp SCMP_A4(enum scmp_compare " op ", " ... ");"
	23	.BI "struct scmp_arg_cmp SCMP_A5(enum scmp_compare " op ", " ... ");"
	24	.sp
	25	.BI "int seccomp_rule_add(scmp_filter_ctx " ctx ", uint32_t " action ","
	26	.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
	27	.BI "int seccomp_rule_add_exact(scmp_filter_ctx " ctx ", uint32_t " action ","
	28	.BI " int " syscall ", unsigned int " arg_cnt ", " ... ");"
	29	.sp
	30	.BI "int seccomp_rule_add_array(scmp_filter_ctx " ctx ","
	31	.BI " uint32_t " action ", int " syscall ","
	32	.BI " unsigned int " arg_cnt ","
	33	.BI " const struct scmp_arg_cmp *"arg_array ");"
	34	.BI "int seccomp_rule_add_exact_array(scmp_filter_ctx " ctx ","
	35	.BI " uint32_t " action ", int " syscall ","
	36	.BI " unsigned int " arg_cnt ","
	37	.BI " const struct scmp_arg_cmp *"arg_array ");"
	38	.sp
	39	Link with \fI\-lseccomp\fP.
	40	.fi
	41	.\" //////////////////////////////////////////////////////////////////////////
	42	.SH DESCRIPTION
	43	.\" //////////////////////////////////////////////////////////////////////////
	44	.P
	45	The
	46	.BR seccomp_rule_add (),
	47	.BR seccomp_rule_add_array (),
	48	.BR seccomp_rule_add_exact (),
	49	and
	50	.BR seccomp_rule_add_exact_array ()
	51	functions all add a new filter rule to the current seccomp filter. The
	52	.BR seccomp_rule_add ()
	53	and
	54	.BR seccomp_rule_add_array ()
	55	functions will make a "best effort" to add the rule as specified, but may alter
	56	the rule slightly due to architecture specifics, e.g. socket and ipc functions
	57	on x86. The
	58	.BR seccomp_rule_add_exact ()
	59	and
	60	.BR seccomp_rule_add_exact_array ()
	61	functions will attempt to add the rule exactly as specified so it may behave
	62	differently on different architectures. While it does not guarantee a exact
	63	filter ruleset,
	64	.BR seccomp_rule_add ()
65	and
66	.BR seccomp_rule_add_array ()
67	do guarantee the same behavior regardless of the architecture.
68	.P
69	The newly added filter rule does not take effect until the entire filter is
70	loaded into the kernel using
71	.BR seccomp_load (3).
72	.P
73	The
74	.BR SCMP_CMP ()
75	and
76	.BR SCMP_A{0-5} ()
77	macros generate a scmp_arg_cmp structure for use with the above functions. The
78	.BR SCMP_CMP ()
79	macro allows the caller to specify an arbitrary argument along with the
80	comparison operator, mask, and datum values where the
81	.BR SCMP_A{0-5} ()
82	macros are specific to a certain argument. See the EXAMPLES section below.
83	.P
84	While it is possible to specify the
85	.I syscall
86	value directly using the standard
87	.B __NR_syscall
88	values, in order to ensure proper operation across multiple architectures it
89	is highly recommended to use the
90	.BR SCMP_SYS ()
91	macro instead. See the EXAMPLES section below.
92	.P
93	The filter context
94	.I ctx
95	is the value returned by the call to
96	.BR seccomp_init (3).
97	.P
98	Valid
99	.I action
100	values are as follows:
101	.TP
102	.B SCMP_ACT_KILL
103	The thread will be killed by the kernel when it calls a syscall that does not
104	match any of the configured seccomp filter rules.
105	.TP
106	.B SCMP_ACT_TRAP
107	The thread will throw a SIGSYS signal when it calls a syscall that does not
108	match any of the configured seccomp filter rules.
109	.TP
110	.B SCMP_ACT_ERRNO(uint16_t errno)
111	The thread will receive a return value of
112	.I errno
113	when it calls a syscall that does not match any of the configured seccomp filter
114	rules.
115	.TP
116	.B SCMP_ACT_TRACE(uint16_t msg_num)
117	If the thread is being traced and the tracing process specified the
118	.B PTRACE_O_TRACESECCOMP
119	option in the call to
120	.BR ptrace (2),
121	the tracing process will be notified, via
122	.B PTRACE_EVENT_SECCOMP
123	, and the value provided in
124	.I msg_num
125	can be retrieved using the
126	.B PTRACE_GETEVENTMSG
127	option.
128	.TP
129	.B SCMP_ACT_ALLOW
130	The seccomp filter will have no effect on the thread calling the syscall if it
131	does not match any of the configured seccomp filter rules.
132	.P
133	Valid comparison
134	.I op
135	values are as follows:
136	.TP
137	.B SCMP_CMP_NE
138	Matches when the argument value is not equal to the datum value, example:
139	.sp
140	SCMP_CMP(
141	.I arg
142	, SCMP_CMP_NE ,
143	.I datum
144	)
145	.TP
146	.B SCMP_CMP_LT
147	Matches when the argument value is less than the datum value, example:
148	.sp
149	SCMP_CMP(
150	.I arg
151	, SCMP_CMP_LT ,
152	.I datum
153	)
154	.TP
155	.B SCMP_CMP_LE
156	Matches when the argument value is less than or equal to the datum value,
157	example:
158	.sp
159	SCMP_CMP(
160	.I arg
161	, SCMP_CMP_LE ,
162	.I datum
163	)
164	.TP
165	.B SCMP_CMP_EQ
166	Matches when the argument value is equal to the datum value, example:
167	.sp
168	SCMP_CMP(
169	.I arg
170	, SCMP_CMP_EQ ,
171	.I datum
172	)
173	.TP
174	.B SCMP_CMP_GE
175	Matches when the argument value is greater than or equal to the datum value,
176	example:
177	.sp
178	SCMP_CMP(
179	.I arg
180	, SCMP_CMP_GE ,
181	.I datum
182	)
183	.TP
184	.B SCMP_CMP_GT
185	Matches when the argument value is greater than the datum value, example:
186	.sp
187	SCMP_CMP(
188	.I arg
189	, SCMP_CMP_GT ,
190	.I datum
191	)
192	.TP
193	.B SCMP_CMP_MASKED_EQ
194	Matches when the masked argument value is equal to the masked datum value,
195	example:
196	.sp
197	SCMP_CMP(
198	.I arg
199	, SCMP_CMP_MASKED_EQ ,
200	.I mask
201	,
202	.I datum
203	)
204	.\" //////////////////////////////////////////////////////////////////////////
205	.SH RETURN VALUE
206	.\" //////////////////////////////////////////////////////////////////////////
207	The
208	.BR seccomp_rule_add (),
209	.BR seccomp_rule_add_array (),
210	.BR seccomp_rule_add_exact (),
211	and
212	.BR seccomp_rule_add_exact_array ()
213	functions return zero on success, negative errno values on failure.
214	.\" //////////////////////////////////////////////////////////////////////////
215	.SH EXAMPLES
216	.\" //////////////////////////////////////////////////////////////////////////
217	.nf
218	#include <fcntl.h>
219	#include <seccomp.h>
220	#include <sys/stat.h>
221	#include <sys/types.h>
222
223	#define BUF_SIZE 256
224
225	int main(int argc, char *argv[])
226	{
227	int rc = \-1;
228	scmp_filter_ctx ctx;
229	struct scmp_arg_cmp arg_cmp[] = { SCMP_A0(SCMP_CMP_EQ, 2) };
230	int fd;
231	unsigned char buf[BUF_SIZE];
232
233	ctx = seccomp_init(SCMP_ACT_KILL);
234	if (ctx == NULL)
235	goto out;
236
237	/* ... */
238
239	fd = open("file.txt", 0);
240
241	/* ... */
242
243	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(close), 0);
244	if (rc < 0)
245	goto out;
246
247	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(read), 3,
248	SCMP_A0(SCMP_CMP_EQ, fd),
249	SCMP_A1(SCMP_CMP_EQ, (scmp_datum_t)buf),
250	SCMP_A2(SCMP_CMP_LE, BUF_SIZE));
251	if (rc < 0)
252	goto out;
253
254	rc = seccomp_rule_add(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
255	SCMP_CMP(0, SCMP_CMP_EQ, fd));
256	if (rc < 0)
257	goto out;
258
259	rc = seccomp_rule_add_array(ctx, SCMP_ACT_ALLOW, SCMP_SYS(write), 1,
260	arg_cmp);
261	if (rc < 0)
262	goto out;
263
264	rc = seccomp_load(ctx);
265	if (rc < 0)
266	goto out;
267
268	/* ... */
269
270	out:
271	seccomp_release(ctx);
272	return \-rc;
273	}
274	.fi
275	.\" //////////////////////////////////////////////////////////////////////////
276	.SH NOTES
277	.\" //////////////////////////////////////////////////////////////////////////
278	.P
279	While the seccomp filter can be generated independent of the kernel, kernel
280	support is required to load and enforce the seccomp filter generated by
281	libseccomp.
282	.P
283	The libseccomp project site, with more information and the source code
284	repository, can be found at https://github.com/seccomp/libseccomp. This tool,
285	as well as the libseccomp library, is currently under development, please
286	report any bugs at the project site or directly to the author.
287	.\" //////////////////////////////////////////////////////////////////////////
288	.SH AUTHOR
289	.\" //////////////////////////////////////////////////////////////////////////
290	Paul Moore <paul@paul-moore.com>
291	.\" //////////////////////////////////////////////////////////////////////////
292	.SH SEE ALSO
293	.\" //////////////////////////////////////////////////////////////////////////
294	.BR seccomp_syscall_priority (3),
295	.BR seccomp_load (3)