MFC r306257:

Document r306081, i.e. procctl(PROC_TRAPCAP) and sysctl kern.trap_enocap.

MFC r306366:
Editing fixes for r306257, documentation for trapcap.

2 files changed, 98 insertions, 3 deletions

diff --git a/lib/libc/sys/cap_enter.2 b/lib/libc/sys/cap_enter.2
index 807d7ed..a6e4030 100644
--- a/lib/libc/sys/cap_enter.2
+++ b/lib/libc/sys/cap_enter.2
@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 27, 2014
+.Dd September 27, 2016
 .Dt CAP_ENTER 2
 .Os
 .Sh NAME
@@ -69,6 +69,34 @@ appropriately-crafted applications or application components may be run.
 .Fn cap_getmode
 returns a flag indicating whether or not the process is in a capability mode
 sandbox.
+.Sh RUN-TIME SETTINGS
+If the
+.Dv kern.trap_enocap
+sysctl MIB is set to a non-zero value, then for any process executing in a
+capability mode sandbox, any syscall which results in either
+.Er ENOTCAPABLE
+or
+.Er ECAPMODE
+error also generates the synchronous
+.Dv SIGTRAP
+signal to the thread on the syscall return.
+On signal delivery, the
+.Va si_errno
+member of the
+.Fa siginfo
+signal handler parameter is set to the syscall error value,
+and the
+.Va si_code
+member is set to
+.Dv TRAP_CAP .
+.Pp
+See also the
+.Dv PROC_TRAPCAP_CTL
+and
+.Dv PROC_TRAPCAP_STATUS
+operations of the
+.Xr procctl 2
+function for similar per-process functionality.
 .Sh CAVEAT
 Creating effective process sandboxes is a tricky process that involves
 identifying the least possible rights required by the process and then
@@ -111,6 +139,8 @@ points outside the process's allocated address space.
 .Xr cap_fcntls_limit 2 ,
 .Xr cap_ioctls_limit 2 ,
 .Xr cap_rights_limit 2 ,
+.Xr procctl 2 ,
+.Xr sysctl 2 ,
 .Xr fexecve 2 ,
 .Xr cap_sandboxed 3 ,
 .Xr capsicum 4
diff --git a/lib/libc/sys/procctl.2 b/lib/libc/sys/procctl.2
index 88dcfd3..da73fb0 100644
--- a/lib/libc/sys/procctl.2
+++ b/lib/libc/sys/procctl.2
@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 21, 2015
+.Dd September 27, 2016
 .Dt PROCCTL 2
 .Os
 .Sh NAME
@@ -71,7 +71,7 @@ The control request to perform is specified by the
 .Fa cmd
 argument.
 The following commands are supported:
-.Bl -tag -width "PROC_REAP_GETPIDS"
+.Bl -tag -width "Dv PROC_TRAPCAP_STATUS"
 .It Dv PROC_SPROTECT
 Set process protection state.
 This is used to mark a process as protected from being killed if the system
@@ -327,6 +327,67 @@ is set to 0.
 If a debugger is attached,
 .Fa data
 is set to the pid of the debugger process.
+.It Dv PROC_TRAPCAP_CTL
+Controls the capability mode sandbox actions for the specified
+sandboxed processes,
+on a return from any syscall which gives either a
+.Er ENOTCAPABLE
+or
+.Er ECAPMODE
+error.
+If the control is enabled, such errors from the syscalls cause
+delivery of the synchronous
+.Dv SIGTRAP
+signal to the thread immediately before returning from the syscalls.
+.Pp
+Possible values for the
+.Fa data
+argument are:
+.Bl -tag -width "Dv PROC_TRAPCAP_CTL_DISABLE"
+.It Dv PROC_TRAPCAP_CTL_ENABLE
+Enable the
+.Dv SIGTRAP
+signal delivery on capability mode access violations.
+The enabled mode is inherited by the children of the process,
+and is kept after
+.Xr fexecve 2
+calls.
+.It Dv PROC_TRAPCAP_CTL_DISABLE
+Disable the signal delivery on capability mode access violations.
+Note that the global sysctl
+.Dv kern.trap_enocap
+might still cause the signal to be delivered.
+See
+.Xr capsicum 4 .
+.El
+.Pp
+On signal delivery, the
+.Va si_errno
+member of the
+.Fa siginfo
+signal handler parameter is set to the syscall error value,
+and the
+.Va si_code
+member is set to
+.Dv TRAP_CAP .
+.Pp
+See
+.Xr capsicum 4
+for more information about the capability mode.
+.It Dv PROC_TRAPCAP_STATUS
+Return the current status of signalling capability mode access
+violations for the specified process.
+The integer value pointed to by the
+.Fa data
+argument is set to the
+.Dv PROC_TRAPCAP_CTL_ENABLE
+value if the process control enables signal delivery, and to
+.Dv PROC_TRAPCAP_CTL_DISABLE
+otherwise.
+.Pp
+See the note about sysctl
+.Dv kern.trap_enocap
+above, which gives independent global control of signal delivery.
 .El
 .Sh NOTES
 Disabling tracing on a process should not be considered a security
@@ -420,14 +481,18 @@ The value of the integer
 .Fa data
 parameter for the
 .Dv PROC_TRACE_CTL
+or
+.Dv PROC_TRAPCAP_CTL
 request is invalid.
 .El
 .Sh SEE ALSO
 .Xr dtrace 1 ,
+.Xr cap_enter 2,
 .Xr kill 2 ,
 .Xr ktrace 2 ,
 .Xr ptrace 2 ,
 .Xr wait 2 ,
+.Xr capsicum 4 ,
 .Xr hwpmc 4 ,
 .Xr init 8
 .Sh HISTORY