libseccomp/doc/man/man3/seccomp_rule_add.3

   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)