manual page for tame(2). not very good, so i will be hearing from jmc

2 files changed, 383 insertions, 3 deletions

diff --git a/lib/libc/sys/Makefile.inc b/lib/libc/sys/Makefile.inc
index ee9b8ff6737..fe791fd83ff 100644
--- a/lib/libc/sys/Makefile.inc
+++ b/lib/libc/sys/Makefile.inc
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile.inc,v 1.125 2015/04/07 01:27:07 guenther Exp $
+#	$OpenBSD: Makefile.inc,v 1.126 2015/07/19 02:37:29 deraadt Exp $
 #	$NetBSD: Makefile.inc,v 1.35 1995/10/16 23:49:07 jtc Exp $
 #	@(#)Makefile.inc	8.1 (Berkeley) 6/17/93
 
@@ -56,7 +56,7 @@ ASM=	__get_tcb.o __getcwd.o __semctl.o __set_tcb.o __syscall.o \
 	settimeofday.o setuid.o shmat.o shmctl.o shmdt.o \
 	shmget.o shutdown.o sigaction.o sigaltstack.o socket.o \
 	socketpair.o stat.o statfs.o swapctl.o symlink.o \
-	symlinkat.o sync.o sysarch.o umask.o unlink.o unlinkat.o \
+	symlinkat.o sync.o sysarch.o tame.o umask.o unlink.o unlinkat.o \
 	unmount.o utimensat.o utimes.o utrace.o wait4.o write.o writev.o
 
 SRCS+=	${SRCS_${MACHINE_CPU}}
@@ -218,7 +218,7 @@ MAN+=	__get_tcb.2 __thrsigdivert.2 __thrsleep.2 _exit.2 accept.2 \
 	shmctl.2 shmget.2 shutdown.2 sigaction.2 sigaltstack.2 sigpending.2 \
 	sigprocmask.2 sigreturn.2 sigsuspend.2 socket.2 \
 	socketpair.2 stat.2 statfs.2 swapctl.2 symlink.2 \
-	sync.2 sysarch.2 syscall.2 truncate.2 umask.2 unlink.2 \
+	sync.2 sysarch.2 syscall.2 tame.2 truncate.2 umask.2 unlink.2 \
 	utimes.2 utrace.2 vfork.2 wait.2 write.2
 
 MLINKS+=__get_tcb.2 __set_tcb.2
diff --git a/lib/libc/sys/tame.2 b/lib/libc/sys/tame.2
new file mode 100644
index 00000000000..b6ff8ced9eb
--- /dev/null
+++ b/lib/libc/sys/tame.2
@@ -0,0 +1,380 @@
+.\" $OpenBSD: tame.2,v 1.1 2015/07/19 02:37:29 deraadt 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 19 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
+.Nm 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
+.Va TAME_ABORT
+is set, then a non-blockable 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
+.Ar TAME_*
+options below (with the exception of
+.Ar TAME_ABORT )
+permit the following system calls: 
+.Pp
+.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:
+.Bl -tag -width TAME_TMPPATH -offset indent -compact
+.It Xr sysctl 3
+A small set of read-only operations are allowed, sufficient to
+support:
+.Xr getifaddrs 3 ,
+.Xr getdomainname 3 ,
+.Xr gethostname 3 ,
+system sensor readings.
+.It Xr access 2
+May check for existance 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
+in below the directory
+.Pa /usr/share/nls/ .
+.It Xr readlink 2
+May operate on
+.Pa /etc/malloc.conf .
+.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 -compact
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar TAME_STDIO
+This subset is simply the combination of
+.Ar TAME_MALLOC
+and
+.Ar TAME_RW .
+As a result, all functionalities of libc 
+stdio works.
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar 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 .
+.Pp
+.It Ar TAME_INET
+The following system calls are allowed to operate in the
+.Ar AF_INET
+and
+.Ar 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 Ar TAME_UNIX
+The following system calls are allowed to operate in the
+.Ar 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 .
+.Pp
+.It Ar TAME_DNSPATH
+Subsequent to a succesfull
+.Xr open 2
+of
+.Pa /etc/resolv.conf ,
+a few system calls become to allow DNS network transactions:
+.Pp
+.Xr sendto 2 ,
+.Xr recvfrom 2 ,
+.Xr socket 2 ,
+.Xr connect 2 .
+.Pp
+.It Ar 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 succesfull
+.Xr open 2
+of
+.Pa /var/run/ypbind.lock
+enables the
+.Ar TAME_INET
+flag.
+.Pp
+.It Ar TAME_CMSG
+Allows passing of file descriptors using the
+.Xr sendmsg 2
+and
+.Xr recvmsg 2
+functions.
+.Pp
+.It Ar TAME_IOCTL
+Allows a subset of
+.Xr ioctl 2
+operations:
+.Pp
+.Va FIOCLEX ,
+.Va FIONCLEX ,
+.Va FIONREAD ,
+.Va FIONBIO ,
+.Va FIOGETOWN ,
+.Va TIOCSWINSZ ,
+.Va TIOCSTI .
+.Pp
+.It Ar TAME_PROC
+Allows the following process relationship operations:
+.Pp
+.Xr fork 2 ,
+.Xr vfork 2 ,
+.Xr kill 2 ,
+.Xr setresgid 2 ,
+.Xr SYS_setresuid 2 ,
+.Pp
+.It Ar TAME_ABORT
+Deliver an unblockable SIGABRT upon violation instead of SIGKILL.
+.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 .