lib/libc/sys/cap_enter.2

   1 .\"
   2 .\" Copyright (c) 2008-2009 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" This software was developed at the University of Cambridge Computer
   6 .\" Laboratory with support from a grant from Google, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\"
  17 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  18 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  20 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  21 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  22 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  23 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  24 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  25 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  26 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  27 .\" SUCH DAMAGE.
  28 .\"
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd May 5, 2020
  32 .Dt CAP_ENTER 2
  33 .Os
  34 .Sh NAME
  35 .Nm cap_enter ,
  36 .Nm cap_getmode
  37 .Nd Capability mode system calls
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/capsicum.h
  42 .Ft int
  43 .Fn cap_enter "void"
  44 .Ft int
  45 .Fn cap_getmode "u_int *modep"
  46 .Sh DESCRIPTION
  47 .Fn cap_enter
  48 places the current process into capability mode, a mode of execution in which
  49 processes may only issue system calls operating on file descriptors or
  50 reading limited global system state.
  51 Access to global name spaces, such as file system or IPC name spaces, is
  52 prevented.
  53 If the process is already in a capability mode sandbox, the system call is a
  54 no-op.
  55 Future process descendants created with
  56 .Xr fork 2
  57 or
  58 .Xr pdfork 2
  59 will be placed in capability mode from inception.
  60 .Pp
  61 When combined with
  62 .Xr cap_rights_limit 2 ,
  63 .Xr cap_ioctls_limit 2 ,
  64 .Xr cap_fcntls_limit 2 ,
  65 .Fn cap_enter
  66 may be used to create kernel-enforced sandboxes in which
  67 appropriately-crafted applications or application components may be run.
  68 .Pp
  69 .Fn cap_getmode
  70 returns a flag indicating whether or not the process is in a capability mode
  71 sandbox.
  72 .Sh RUN-TIME SETTINGS
  73 If the
  74 .Dv kern.trap_enotcap
  75 sysctl MIB is set to a non-zero value, then for any process executing in a
  76 capability mode sandbox, any syscall which results in either an
  77 .Er ENOTCAPABLE
  78 or
  79 .Er ECAPMODE
  80 error also generates the synchronous
  81 .Dv SIGTRAP
  82 signal to the thread on the syscall return.
  83 On signal delivery, the
  84 .Va si_errno
  85 member of the
  86 .Fa siginfo
  87 signal handler parameter is set to the syscall error value,
  88 and the
  89 .Va si_code
  90 member is set to
  91 .Dv TRAP_CAP .
  92 .Pp
  93 See also the
  94 .Dv PROC_TRAPCAP_CTL
  95 and
  96 .Dv PROC_TRAPCAP_STATUS
  97 operations of the
  98 .Xr procctl 2
  99 function for similar per-process functionality.
 100 .Sh CAVEAT
 101 Creating effective process sandboxes is a tricky process that involves
 102 identifying the least possible rights required by the process and then
 103 passing those rights into the process in a safe manner.
 104 Consumers of
 105 .Fn cap_enter
 106 should also be aware of other inherited rights, such as access to VM
 107 resources, memory contents, and other process properties that should be
 108 considered.
 109 It is advisable to use
 110 .Xr fexecve 2
 111 to create a runtime environment inside the sandbox that has as few implicitly
 112 acquired rights as possible.
 113 .Sh RETURN VALUES
 114 .Rv -std cap_enter cap_getmode
 115 .Pp
 116 When the process is in capability mode,
 117 .Fn cap_getmode
 118 sets the flag to a non-zero value.
 119 A zero value means the process is not in capability mode.
 120 .Sh ERRORS
 121 The
 122 .Fn cap_enter
 123 and
 124 .Fn cap_getmode
 125 system calls
 126 will fail if:
 127 .Bl -tag -width Er
 128 .It Bq Er ENOSYS
 129 The kernel is compiled without:
 130 .Pp
 131 .Cd "options CAPABILITY_MODE"
 132 .El
 133 .Pp
 134 The
 135 .Fn cap_getmode
 136 system call may also return the following error:
 137 .Bl -tag -width Er
 138 .It Bq Er EFAULT
 139 Pointer
 140 .Fa modep
 141 points outside the process's allocated address space.
 142 .El
 143 .Sh SEE ALSO
 144 .Xr cap_fcntls_limit 2 ,
 145 .Xr cap_ioctls_limit 2 ,
 146 .Xr cap_rights_limit 2 ,
 147 .Xr fexecve 2 ,
 148 .Xr procctl 2 ,
 149 .Xr cap_sandboxed 3 ,
 150 .Xr capsicum 4 ,
 151 .Xr sysctl 9
 152 .Sh HISTORY
 153 The
 154 .Fn cap_getmode
 155 system call first appeared in
 156 .Fx 8.3 .
 157 Support for capabilities and capabilities mode was developed as part of the
 158 .Tn TrustedBSD
 159 Project.
 160 .Sh AUTHORS
 161 These functions and the capability facility were created by
 162 .An "Robert N. M. Watson"
 163 at the University of Cambridge Computer Laboratory with support from a grant
 164 from Google, Inc.