+++ /dev/null
-.\" Copyright (C) 2014 Kees Cook <keescook@chromium.org>
-.\" and Copyright (C) 2012 Will Drewry <wad@chromium.org>
-.\" and Copyright (C) 2008, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
-.\"
-.\" %%%LICENSE_START(VERBATIM)
-.\" Permission is granted to make and distribute verbatim copies of this
-.\" manual provided the copyright notice and this permission notice are
-.\" preserved on all copies.
-.\"
-.\" Permission is granted to copy and distribute modified versions of this
-.\" manual under the conditions for verbatim copying, provided that the
-.\" entire resulting derived work is distributed under the terms of a
-.\" permission notice identical to this one.
-.\"
-.\" Since the Linux kernel and libraries are constantly changing, this
-.\" manual page may be incorrect or out-of-date. The author(s) assume no
-.\" responsibility for errors or omissions, or for damages resulting from
-.\" the use of the information contained herein. The author(s) may not
-.\" have taken the same level of care in the production of this manual,
-.\" which is licensed free of charge, as they might when working
-.\" professionally.
-.\"
-.\" Formatted or processed versions of this manual, if unaccompanied by
-.\" the source, must acknowledge the copyright and authors of this work.
-.\" %%%LICENSE_END
-.\"
-.TH SECCOMP 2 2015-01-10 "Linux" "Linux Programmer's Manual"
-.SH NAME
-seccomp \- operate on Secure Computing state of the process
-.SH SYNOPSIS
-.nf
-.B #include <linux/seccomp.h>
-.B #include <linux/filter.h>
-.B #include <linux/audit.h>
-.B #include <linux/signal.h>
-.B #include <sys/ptrace.h>
-.\" Kees Cook noted: Anything that uses SECCOMP_RET_TRACE returns will
-.\" need <sys/ptrace.h>
-
-.BI "int seccomp(unsigned int " operation ", unsigned int " flags \
-", void *" args );
-.fi
-.SH DESCRIPTION
-The
-.BR seccomp ()
-system call operates on the Secure Computing (seccomp) state of the
-calling process.
-
-Currently, Linux supports the following
-.IR operation
-values:
-.TP
-.BR SECCOMP_SET_MODE_STRICT
-The only system calls that the calling thread is permitted to make are
-.BR read (2),
-.BR write (2),
-.BR _exit (2),
-and
-.BR sigreturn (2).
-Other system calls result in the delivery of a
-.BR SIGKILL
-signal.
-Strict secure computing mode is useful for number-crunching
-applications that may need to execute untrusted byte code, perhaps
-obtained by reading from a pipe or socket.
-
-This operation is available only if the kernel is configured with
-.BR CONFIG_SECCOMP
-enabled.
-
-The value of
-.IR flags
-must be 0, and
-.IR args
-must be NULL.
-
-This operation is functionally identical to the call:
-
- prctl(PR_SET_SECCOMP, SECCOMP_MODE_STRICT);
-.TP
-.BR SECCOMP_SET_MODE_FILTER
-The system calls allowed are defined by a pointer to a Berkeley Packet
-Filter (BPF) passed via
-.IR args .
-This argument is a pointer to a
-.IR "struct\ sock_fprog" ;
-it can be designed to filter arbitrary system calls and system call
-arguments.
-If the filter is invalid,
-.BR seccomp ()
-fails, returning
-.BR EINVAL
-in
-.IR errno .
-
-If
-.BR fork (2)
-or
-.BR clone (2)
-is allowed by the filter, any child processes will be constrained to
-the same system call filters as the parent.
-If
-.BR execve (2)
-is allowed,
-the existing filters will be preserved across a call to
-.BR execve (2).
-
-In order to use the
-.BR SECCOMP_SET_MODE_FILTER
-operation, either the caller must have the
-.BR CAP_SYS_ADMIN
-capability, or the thread must already have the
-.I no_new_privs
-bit set.
-If that bit was not already set by an ancestor of this thread,
-the thread must make the following call:
-
- prctl(PR_SET_NO_NEW_PRIVS, 1);
-
-Otherwise, the
-.BR SECCOMP_SET_MODE_FILTER
-operation will fail and return
-.BR EACCES
-in
-.IR errno .
-This requirement ensures that an unprivileged process cannot apply
-a malicious filter and then invoke a set-user-ID or
-other privileged program using
-.BR execve (2),
-thus potentially compromising that program.
-(Such a malicious filter might, for example, cause an attempt to use
-.BR setuid (2)
-to set the caller's user IDs to non-zero values to instead
-return 0 without actually making the system call.
-Thus, the program might be tricked into retaining superuser privileges
-in circumstances where it is possible to influence it to do
-dangerous things because it did not actually drop privileges.)
-
-If
-.BR prctl (2)
-or
-.BR seccomp (2)
-is allowed by the attached filter, further filters may be added.
-This will increase evaluation time, but allows for further reduction of
-the attack surface during execution of a thread.
-
-The
-.BR SECCOMP_SET_MODE_FILTER
-operation is available only if the kernel is configured with
-.BR CONFIG_SECCOMP_FILTER
-enabled.
-
-When
-.IR flags
-is 0, this operation is functionally identical to the call:
-
- prctl(PR_SET_SECCOMP, SECCOMP_MODE_FILTER, args);
-
-The recognized
-.IR flags
-are:
-.RS
-.TP
-.BR SECCOMP_FILTER_FLAG_TSYNC
-When adding a new filter, synchronize all other threads of the calling
-process to the same seccomp filter tree.
-A "filter tree" is the ordered list of filters attached to a thread.
-(Attaching identical filters in separate
-.BR seccomp ()
-calls results in different filters from this perspective.)
-
-If any thread cannot synchronize to the same filter tree,
-the call will not attach the new seccomp filter,
-and will fail, returning the first thread ID found that cannot synchronize.
-Synchronization will fail if another thread in the same process is in
-.BR SECCOMP_MODE_STRICT
-or if it has attached new seccomp filters to itself,
-diverging from the calling thread's filter tree.
-.RE
-.SS Filters
-When adding filters via
-.BR SECCOMP_SET_MODE_FILTER ,
-.IR args
-points to a filter program:
-
-.in +4n
-.nf
-struct sock_fprog {
- unsigned short len; /* Number of BPF instructions */
- struct sock_filter *filter; /* Pointer to array of
- BPF instructions */
-};
-.fi
-.in
-
-Each program must contain one or more BPF instructions:
-
-.in +4n
-.nf
-struct sock_filter { /* Filter block */
- __u16 code; /* Actual filter code */
- __u8 jt; /* Jump true */
- __u8 jf; /* Jump false */
- __u32 k; /* Generic multiuse field */
-};
-.fi
-.in
-
-When executing the instructions, the BPF program operates on the
-system call information made available (i.e., use the
-.BR BPF_ABS
-addressing mode) as a buffer of the following form:
-
-.in +4n
-.nf
-struct seccomp_data {
- int nr; /* System call number */
- __u32 arch; /* AUDIT_ARCH_* value
- (see <linux/audit.h>) */
- __u64 instruction_pointer; /* CPU instruction pointer */
- __u64 args[6]; /* Up to 6 system call arguments */
-};
-.fi
-.in
-
-A seccomp filter returns a 32-bit value consisting of two parts:
-the most significant 16 bits
-(corresponding to the mask defined by the constant
-.BR SECCOMP_RET_ACTION )
-contain one of the "action" values listed below;
-the least significant 16-bits (defined by the constant
-.BR SECCOMP_RET_DATA )
-are "data" to be associated with this return value.
-
-If multiple filters exist, they are all executed,
-in reverse order of their addition to the filter tree
-(i.e., the most recently installed filter is executed first).
-The return value for the evaluation of a given system call is the first-seen
-.BR SECCOMP_RET_ACTION
-value of highest precedence (along with its accompanying data)
-returned by execution of all of the filters.
-
-In decreasing order of precedence,
-the values that may be returned by a seccomp filter are:
-.TP
-.BR SECCOMP_RET_KILL
-This value results in the process exiting immediately
-without executing the system call.
-The process terminates as though killed by a
-.B SIGSYS
-signal
-.RI ( not
-.BR SIGKILL ).
-.TP
-.BR SECCOMP_RET_TRAP
-This value results in the kernel sending a
-.BR SIGSYS
-signal to the triggering process without executing the system call.
-Various fields will be set in the
-.I siginfo_t
-structure (see
-.BR sigaction (2))
-associated with signal:
-.RS
-.IP * 3
-.I si_signo
-will contain
-.BR SIGSYS .
-.IP *
-.IR si_call_addr
-will show the address of the system call instruction.
-.IP *
-.IR si_syscall
-and
-.IR si_arch
-will indicate which system call was attempted.
-.IP *
-.I si_code
-will contain
-.BR SYS_SECCOMP .
-.IP *
-.I si_errno
-will contain the
-.BR SECCOMP_RET_DATA
-portion of the filter return value.
-.RE
-.IP
-The program counter will be as though the system call happened
-(i.e., it will not point to the system call instruction).
-The return value register will contain an architecture\-dependent value;
-if resuming execution, set it to something appropriate for the system call.
-(The architecture dependency is because replacing it with
-.BR ENOSYS
-could overwrite some useful information.)
-.TP
-.BR SECCOMP_RET_ERRNO
-This value results in the
-.B SECCOMP_RET_DATA
-portion of the filter's return value being passed to user space as the
-.IR errno
-value without executing the system call.
-.TP
-.BR SECCOMP_RET_TRACE
-When returned, this value will cause the kernel to attempt to notify a
-.BR ptrace (2)-based
-tracer prior to executing the system call.
-If there is no tracer present,
-the system call is not executed and returns a failure status with
-.I errno
-set to
-.BR ENOSYS .
-
-A tracer will be notified if it requests
-.BR PTRACE_O_TRACESECCOMP
-using
-.IR ptrace(PTRACE_SETOPTIONS) .
-The tracer will be notified of a
-.BR PTRACE_EVENT_SECCOMP
-and the
-.BR SECCOMP_RET_DATA
-portion of the filter's return value will be available to the tracer via
-.BR PTRACE_GETEVENTMSG .
-
-The tracer can skip the system call by changing the system call number
-to \-1.
-Alternatively, the tracer can change the system call
-requested by changing the system call to a valid system call number.
-If the tracer asks to skip the system call, then the system call will
-appear to return the value that the tracer puts in the return value register.
-
-The seccomp check will not be run again after the tracer is notified.
-(This means that seccomp-based sandboxes
-.B "must not"
-allow use of
-.BR ptrace (2)\(emeven
-of other
-sandboxed processes\(emwithout extreme care;
-ptracers can use this mechanism to escape from the seccomp sandbox.)
-.TP
-.BR SECCOMP_RET_ALLOW
-This value results in the system call being executed.
-.SH RETURN VALUE
-On success,
-.BR seccomp ()
-returns 0.
-On error, if
-.BR SECCOMP_FILTER_FLAG_TSYNC
-was used,
-the return value is the ID of the thread
-that caused the synchronization failure.
-(This ID is a kernel thread ID of the type returned by
-.BR clone (2)
-and
-.BR gettid (2).)
-On other errors, \-1 is returned, and
-.IR errno
-is set to indicate the cause of the error.
-.SH ERRORS
-.BR seccomp ()
-can fail for the following reasons:
-.TP
-.BR EACCESS
-The caller did not have the
-.BR CAP_SYS_ADMIN
-capability, or had not set
-.IR no_new_privs
-before using
-.BR SECCOMP_SET_MODE_FILTER .
-.TP
-.BR EFAULT
-.IR args
-was not a valid address.
-.TP
-.BR EINVAL
-.IR operation
-is unknown; or
-.IR flags
-are invalid for the given
-.IR operation .
-.TP
-.BR EINVAL
-.I operation
-included
-.BR BPF_ABS ,
-but the specified offset was not aligned to a 32-bit boundary or exceeded
-.IR "sizeof(struct\ seccomp_data)" .
-.TP
-.BR EINVAL
-.\" See kernel/seccomp.c::seccomp_may_assign_mode() in 3.18 sources
-A secure computing mode has already been set, and
-.I operation
-differs from the existing setting.
-.TP
-.BR EINVAL
-.\" See stub kernel/seccomp.c::seccomp_set_mode_filter() in 3.18 sources
-.I operation
-specified
-.BR SECCOMP_SET_MODE_FILTER ,
-but the kernel was not built with
-.B CONFIG_SECCOMP_FILTER
-enabled.
-.TP
-.BR EINVAL
-.I operation
-specified
-.BR SECCOMP_SET_MODE_FILTER ,
-but the filter program pointed to by
-.I args
-was not valid or the length of the filter program was zero or exceeded
-.B BPF_MAXINSNS
-(4096) instructions.
-.BR EINVAL
-.TP
-.BR ENOMEM
-Out of memory.
-.TP
-.BR ENOMEM
-.\" ENOMEM in kernel/seccomp.c::seccomp_attach_filter() in 3.18 sources
-The total length of all filter programs attached
-to the calling thread would exceed
-.B MAX_INSNS_PER_PATH
-(32768) instructions.
-Note that for the purposes of calculating this limit,
-each already existing filter program incurs an
-overhead penalty of 4 instructions.
-.TP
-.BR ESRCH
-Another thread caused a failure during thread sync, but its ID could not
-be determined.
-.SH VERSIONS
-The
-.BR seccomp ()
-system call first appeared in Linux 3.17.
-.\" FIXME . Add glibc version
-.SH CONFORMING TO
-The
-.BR seccomp ()
-system call is a nonstandard Linux extension.
-.SH NOTES
-The
-.IR Seccomp
-field of the
-.IR /proc/[pid]/status
-file provides a method of viewing the seccomp mode of a process; see
-.BR proc (5).
-
-.BR seccomp ()
-provides a superset of the functionality provided by the
-.BR prctl (2)
-.BR PR_SET_SECCOMP
-operation (which does not support
-.IR flags ).
-.SS Seccomp-specific BPF details
-Note the following BPF details specific to seccomp filters:
-.IP * 3
-The
-.B BPF_H
-and
-.B BPF_B
-size modifiers are not supported: all operations must load and store
-(4-byte) words
-.RB ( BPF_W ).
-.IP *
-To access the contents of the
-.I seccomp_data
-buffer, use the
-.B BPF_ABS
-addressing mode modifier.
-.IP *
-The
-.B BPF_LEN
-addressing mode modifier yields an immediate mode operand
-whose value is the size of the
-.IR seccomp_data
-buffer.
-.SH EXAMPLE
-The program below accepts four or more arguments.
-The first three arguments are a system call number,
-a numeric architecture identifier, and an error number.
-The program uses these values to construct a BPF filter
-that is used at run time to perform the following checks:
-.IP [1] 4
-If the program is not running on the specified architecture,
-the BPF filter causes system calls to fail with the error
-.BR ENOSYS .
-.IP [2]
-If the program attempts to execute the system call with the specified number,
-the BPF filter causes the system call to fail, with
-.I errno
-being set to the specified error number.
-.PP
-The remaining command-line arguments specify
-the pathname and additional arguments of a program
-that the example program should attempt to execute using
-.BR execve (3)
-(a library function that employs the
-.BR execve (2)
-system call).
-Some example runs of the program are shown below.
-
-First, we display the architecture that we are running on (x86-64)
-and then construct a shell function that looks up system call
-numbers on this architecture:
-
-.nf
-.in +4n
-$ \fBuname -m\fP
-x86_64
-$ \fBsyscall_nr() {
- cat /usr/src/linux/arch/x86/syscalls/syscall_64.tbl | \\
- awk '$2 != "x32" && $3 == "'$1'" { print $1 }'
-}\fP
-.in
-.fi
-
-When the BPF filter rejects a system call (case [2] above),
-it causes the system call to fail with the error number
-specified on the command line.
-In the experiments shown here, we'll use error number 99:
-
-.nf
-.in +4n
-$ \fBerrno 99\fP
-EADDRNOTAVAIL 99 Cannot assign requested address
-.in
-.fi
-
-In the following example, we attempt to run the command
-.BR whoami (1),
-but the BPF filter rejects the
-.BR execve (2)
-system call, so that the command is not even executed:
-
-.nf
-.in +4n
-$ \fBsyscall_nr execve\fP
-59
-$ \fB./a.out\fP
-Usage: ./a.out <syscall_nr> <arch> <errno> <prog> [<args>]
-Hint for <arch>: AUDIT_ARCH_I386: 0x40000003
- AUDIT_ARCH_X86_64: 0xC000003E
-$ \fB./a.out 59 0xC000003E 99 /bin/whoami\fP
-execv: Cannot assign requested address
-.in
-.fi
-
-In the next example, the BPF filter rejects the
-.BR write (2)
-system call, so that, although it is successfully started, the
-.BR whoami (1)
-command is not able to write output:
-
-.nf
-.in +4n
-$ \fBsyscall_nr write\fP
-1
-$ \fB./a.out 1 0xC000003E 99 /bin/whoami\fP
-.in
-.fi
-
-In the final example,
-the BPF filter rejects a system call that is not used by the
-.BR whoami (1)
-command, so it is able to successfully execute and produce output:
-
-.nf
-.in +4n
-$ \fBsyscall_nr preadv\fP
-295
-$ \fB./a.out 295 0xC000003E 99 /bin/whoami\fP
-cecilia
-.in
-.fi
-.SS Program source
-.fi
-.nf
-#include <errno.h>
-#include <stddef.h>
-#include <stdio.h>
-#include <stdlib.h>
-#include <unistd.h>
-#include <linux/audit.h>
-#include <linux/filter.h>
-#include <linux/seccomp.h>
-#include <sys/prctl.h>
-
-static int
-install_filter(int syscall_nr, int t_arch, int f_errno)
-{
- struct sock_filter filter[] = {
- /* [0] Load architecture from 'seccomp_data' buffer into
- accumulator */
- BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
- (offsetof(struct seccomp_data, arch))),
-
- /* [1] Jump forward 4 instructions if architecture does not
- match 't_arch' */
- BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, t_arch, 0, 4),
-
- /* [2] Load system call number from 'seccomp_data' buffer into
- accumulator */
- BPF_STMT(BPF_LD | BPF_W | BPF_ABS,
- (offsetof(struct seccomp_data, nr))),
-
- /* [3] Jump forward 1 instruction if system call number
- does not match 'syscall_nr' */
- BPF_JUMP(BPF_JMP | BPF_JEQ | BPF_K, syscall_nr, 0, 1),
-
- /* [4] Matching architecture and system call: don't execute
- the system call, and return 'f_errno' in 'errno' */
- BPF_STMT(BPF_RET | BPF_K,
- SECCOMP_RET_ERRNO | (f_errno & SECCOMP_RET_DATA)),
-
- /* [5] Destination of system call number mismatch: allow other
- system calls */
- BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_ALLOW),
-
- /* [6] Destination of architecture mismatch: kill process */
- BPF_STMT(BPF_RET | BPF_K, SECCOMP_RET_KILL),
- };
-
- struct sock_fprog prog = {
- .len = (unsigned short) (sizeof(filter) / sizeof(filter[0])),
- .filter = filter,
- };
-
- if (seccomp(SECCOMP_SET_MODE_FILTER, 0, &prog)) {
- perror("seccomp");
- return 1;
- }
-
- return 0;
-}
-
-int
-main(int argc, char **argv)
-{
- if (argc < 5) {
- fprintf(stderr, "Usage: "
- "%s <syscall_nr> <arch> <errno> <prog> [<args>]\\n"
- "Hint for <arch>: AUDIT_ARCH_I386: 0x%X\\n"
- " AUDIT_ARCH_X86_64: 0x%X\\n"
- "\\n", argv[0], AUDIT_ARCH_I386, AUDIT_ARCH_X86_64);
- exit(EXIT_FAILURE);
- }
-
- if (prctl(PR_SET_NO_NEW_PRIVS, 1, 0, 0, 0)) {
- perror("prctl");
- exit(EXIT_FAILURE);
- }
-
- if (install_filter(strtol(argv[1], NULL, 0),
- strtol(argv[2], NULL, 0),
- strtol(argv[3], NULL, 0)))
- exit(EXIT_FAILURE);
-
- execv(argv[4], &argv[4]);
- perror("execv");
- exit(EXIT_FAILURE);
-}
-.fi
-.SH SEE ALSO
-.BR prctl (2),
-.BR ptrace (2),
-.BR sigaction (2),
-.BR signal (7),
-.BR socket (7)
-.sp
-The kernel source files
-.IR Documentation/networking/filter.txt
-and
-.IR Documentation/prctl/seccomp_filter.txt .
-.sp
-McCanne, S. and Jacobson, V. (1992)
-.IR "The BSD Packet Filter: A New Architecture for User-level Packet Capture" ,
-Proceedings of the USENIX Winter 1993 Conference
-.UR http://www.tcpdump.org/papers/bpf-usenix93.pdf
-.UE
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
