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

Reviewed by:	cem
Sponsored by:	The FreeBSD Foundation
MFC after:	1 week
Differential revision:	https://reviews.freebsd.org/D8003

lib/libc/sys/cap_enter.2

@@ -28,7 +28,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd September 10, 2016
+.Dd September 22, 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 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 the 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
@@ -116,6 +144,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

lib/libc/sys/procctl.2

@@ -29,7 +29,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd August 21, 2015
+.Dd September 22, 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,63 @@ 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
+Enable or disable, for the specified processes which are executing in a
+capability mode sandbox, the synchronous
+.Dv SIGTRAP
+signal on return from any syscall which gives either
+.Er ENOTCAPABLE
+or
+.Er ECAPMODE
+error.
+.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
+Returns 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 +477,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