path: root/lib/libc/sys/tame.2

.\" $OpenBSD: tame.2,v 1.13 2015/07/23 05:44:40 doug Exp $
.\"
.\" Copyright (c) 2015 Nicholas Marriott <nicm@openbsd.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd $Mdocdate: July 23 2015 $
.Dt TAME 2
.Os
.Sh NAME
.Nm tame
.Nd restrict system operations
.Sh SYNOPSIS
.In sys/tame.h
.Ft int
.Fn tame "int flags"
.Sh DESCRIPTION
The current process is forced into a restricted-service operating mode.
A few subsets are available, roughly described as computation, memory
management, read-write operations on file descriptors, opening of files,
networking.
In general, these modes were selected by studying the operation
of many programs using libc and other such interfaces.
.Pp
Use of
.Fn tame
in an application will require at least some study and understanding
of the interfaces called.
.Pp
Subsequent calls to
.Fn tame
can reduce abilities further, but abilities can never be regained.
.Pp
A process which attempts a restricted operation is killed with
.Dv SIGKILL .
If
.Dv TAME_ABORT
is set, then a non-blockable
.Dv SIGABRT
is delivered instead, possibly resulting in a
.Xr core 5
file.
.Pp
A
.Fa flags
value of 0 restricts the process to the
.Xr _exit 2
system call.
This can be used for pure computation operating on memory shared
with another process.
.Pp
All
.Dv TAME_*
options below (with the exception of
.Dv TAME_ABORT )
permit the following system calls:
.Bd -ragged -offset indent
.Xr clock_getres 2 ,
.Xr clock_gettime 2 ,
.Xr fchdir 2 ,
.Xr getdtablecount 2 ,
.Xr getegid 2 ,
.Xr geteuid 2 ,
.Xr getgid 2 ,
.Xr getgroups 2 ,
.Xr getitimer 2 ,
.Xr getlogin 2 ,
.Xr getpgid 2 ,
.Xr getpgrp 2 ,
.Xr getpid 2 ,
.Xr getppid 2 ,
.Xr getresgid 2 ,
.Xr getresuid 2 ,
.Xr getrlimit 2 ,
.Xr getsid 2 ,
.Xr getthrid 2 ,
.Xr gettimeofday 2 ,
.Xr getuid 2 ,
.Xr getuid 2 ,
.Xr issetugid 2 ,
.Xr nanosleep 2 ,
.Xr sendsyslog 2 ,
.Xr setitimer 2 ,
.Xr sigaction 2 ,
.Xr sigprocmask 2 ,
.Xr sigreturn 2 ,
.Xr umask 2 ,
.Xr wait4 2 .
.Ed
.Pp
Calls allowed with restrictions include:
.Pp
.Bl -tag -width TAME_TMPPATH -offset indent -compact
.It Xr access 2
May check for existence of
.Pa /etc/localtime .
.It Xr adjtime 2
Read-only, for
.Xr ntpd 8 .
.It Xr open 2
May open
.Pa /etc/localtime ,
any files below
.Pa /usr/share/zoneinfo
and files ending in
.Pa libc.cat
below the directory
.Pa /usr/share/nls/ .
.It Xr readlink 2
May operate on
.Pa /etc/malloc.conf .
.It Xr sysctl 3
A small set of read-only operations are allowed, sufficient to
support:
.Xr getdomainname 3 ,
.Xr gethostname 3 ,
.Xr getifaddrs 3 ,
.Xr uname 3 ,
system sensor readings.
.It Xr tame 2
Can only reduce permissions.
.El
.Pp
The
.Ar flags
are specified as a bitwise OR of the following values:
.Bl -tag -width TAME_TMPPATH -offset indent
.It Dv TAME_ABORT
Deliver an unblockable
.Dv SIGABRT
upon violation instead of
.Dv SIGKILL .
.It Dv TAME_CMSG
Allows passing of file descriptors using the
.Xr sendmsg 2
and
.Xr recvmsg 2
functions.
.It Dv TAME_CPATH
A number of system calls and sub-modes are allowed, which may
create new files or directories in the filesystem:
.Pp
.Xr rename 2 ,
.Xr rmdir 2 ,
.Xr renameat 2 ,
.Xr link 2 ,
.Xr linkat 2 ,
.Xr symlink 2 ,
.Xr unlink 2 ,
.Xr unlinkat 2 ,
.Xr mkdir 2 ,
.Xr mkdirat 2 .
.It Dv TAME_DNS
Subsequent to a successful
.Xr open 2
of
.Pa /etc/resolv.conf ,
a few system calls become able to allow DNS network transactions:
.Pp
.Xr sendto 2 ,
.Xr recvfrom 2 ,
.Xr socket 2 ,
.Xr connect 2 .
.It Dv TAME_GETPW
This allows read-only opening of files in
.Pa /etc
for the
.Xr getpwnam 3 ,
.Xr getgrnam 3 ,
.Xr getgrouplist 3 ,
and
.Xr initgroups 3
family of functions.
They may also need to operate in a
.Xr yp 8
environment, so a successful
.Xr open 2
of
.Pa /var/run/ypbind.lock
enables the
.Dv TAME_INET
flag.
.It Dv TAME_INET
The following system calls are allowed to operate in the
.Dv AF_INET
and
.Dv AF_INET6
domains:
.Pp
.Xr socket 2 ,
.Xr listen 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr accept4 2 ,
.Xr accept 2 ,
.Xr getpeername 2 ,
.Xr getsockname 2 ,
.Xr setsockopt 2 ,
.Xr getsockopt 2 .
.Pp
.Xr setsockopt 2
has been reduced in functionality substantially.
.It Dv TAME_IOCTL
Allows a subset of
.Xr ioctl 2
operations:
.Pp
.Dv FIOCLEX ,
.Dv FIONCLEX ,
.Dv FIONREAD ,
.Dv FIONBIO ,
.Dv FIOGETOWN ,
.Dv TIOCGWINSZ ,
.Dv TIOCSTI .
.It Dv TAME_MALLOC
To allow use of the
.Xr malloc 3
family of functions, the following system calls are permitted:
.Pp
.Xr getentropy 2 ,
.Xr madvise 2 ,
.Xr minherit 2 ,
.Xr mmap 2 ,
.Xr mprotect 2 ,
.Xr mquery 2 ,
.Xr munmap 2 .
.It Dv TAME_PROC
Allows the following process relationship operations:
.Pp
.Xr fork 2 ,
.Xr vfork 2 ,
.Xr kill 2 ,
.Xr setgroups 2 ,
.Xr setresgid 2 ,
.Xr setresuid 2 ,
.It Dv TAME_RPATH
A number of system calls are allowed if they only cause
read-only effects on the filesystem:
.Pp
.Xr chdir 2 ,
.Xr getcwd 3 ,
.Xr openat 2 ,
.Xr fstatat 2 ,
.Xr faccessat 2 ,
.Xr readlinkat 2 ,
.Xr lstat 2 ,
.Xr chmod 2 ,
.Xr fchmod 2 ,
.Xr fchmodat 2 ,
.Xr chflags 2 ,
.Xr chflagsat 2 ,
.Xr chown 2 ,
.Xr fchown 2 ,
.Xr fchownat 2 ,
.Xr fstat 2 .
.It Dv TAME_RW
The following system calls are permitted to allow most types of IO
operations on previously allocated file descriptors, including
libevent or handwritten async IO loops:
.Pp
.Xr poll 2 ,
.Xr kevent 2 ,
.Xr kqueue 2 ,
.Xr select 2 ,
.Xr close 2 ,
.Xr dup 2 ,
.Xr dup2 2 ,
.Xr dup3 2 ,
.Xr closefrom 2 ,
.Xr shutdown 2 ,
.Xr read 2 ,
.Xr readv 2 ,
.Xr pread 2 ,
.Xr preadv 2 ,
.Xr write 2 ,
.Xr writev 2 ,
.Xr pwrite 2 ,
.Xr pwritev 2 ,
.Xr ftruncate 2 ,
.Xr lseek 2 ,
.Xr utimes 2 ,
.Xr futimes 2 ,
.Xr utimensat 2 ,
.Xr futimens 2 ,
.Xr fcntl 2 ,
.Xr fsync 2 ,
.Xr pipe 2 ,
.Xr pipe2 2 ,
.Xr socketpair 2 ,
.Xr getdents 2 ,
.Xr sendto 2 ,
.Xr sendmsg 2 ,
.Xr recvmsg 2 ,
.Xr recvfrom 2 ,
.Xr fstat 2 .
.It Dv TAME_STDIO
This subset is simply the combination of
.Dv TAME_MALLOC
and
.Dv TAME_RW .
As a result, all functionalities of libc
stdio works.
.It Dv TAME_TMPPATH
A number of system calls are allowed to do operations in the
.Pa /tmp
directory, including create, read, or write:
.Pp
.Xr lstat 2 ,
.Xr chmod 2 ,
.Xr chflags 2 ,
.Xr chown 2 ,
.Xr unlink 2 ,
.Xr fstat 2 .
.It Dv TAME_UNIX
The following system calls are allowed to operate in the
.Dv AF_UNIX
domain:
.Pp
.Xr socket 2 ,
.Xr listen 2 ,
.Xr bind 2 ,
.Xr connect 2 ,
.Xr accept4 2 ,
.Xr accept 2 ,
.Xr getpeername 2 ,
.Xr getsockname 2 ,
.Xr setsockopt 2 ,
.Xr getsockopt 2 .
.It Dv TAME_WPATH
A number of system calls are allowed and may cause
write-effects on the filesystem:
.Pp
.Xr getcwd 3 ,
.Xr openat 2 ,
.Xr fstatat 2 ,
.Xr faccessat 2 ,
.Xr readlinkat 2 ,
.Xr lstat 2 ,
.Xr chmod 2 ,
.Xr fchmod 2 ,
.Xr fchmodat 2 ,
.Xr chflags 2 ,
.Xr chflagsat 2 ,
.Xr chown 2 ,
.Xr fchown 2 ,
.Xr fchownat 2 ,
.Xr fstat 2 ,
.Xr fstat 2 .
.El
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
.Fn tame
will fail if:
.Bl -tag -width Er
.It Bq Er EPERM
This process is attempting to increase permissions.
.El
.Sh HISTORY
The
.Fn tame
system call appeared in
.Ox 5.8 .