svn commit: r306257 - head/lib/libc/sys
Konstantin Belousov
kib at FreeBSD.org
Fri Sep 23 09:26:41 UTC 2016
Author: kib
Date: Fri Sep 23 09:26:40 2016
New Revision: 306257
URL: https://svnweb.freebsd.org/changeset/base/306257
Log:
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
Modified:
head/lib/libc/sys/cap_enter.2
head/lib/libc/sys/procctl.2
Modified: head/lib/libc/sys/cap_enter.2
==============================================================================
--- head/lib/libc/sys/cap_enter.2 Fri Sep 23 09:20:42 2016 (r306256)
+++ head/lib/libc/sys/cap_enter.2 Fri Sep 23 09:26:40 2016 (r306257)
@@ -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 ap
.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 a
.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
Modified: head/lib/libc/sys/procctl.2
==============================================================================
--- head/lib/libc/sys/procctl.2 Fri Sep 23 09:20:42 2016 (r306256)
+++ head/lib/libc/sys/procctl.2 Fri Sep 23 09:26:40 2016 (r306257)
@@ -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 specif
.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
More information about the svn-src-head
mailing list