lib/libc/posix1e/cap.3

   1 .\"-
   2 .\" Copyright (c) 2000 Robert N. M. Watson
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD$
  27 .\"
  28 .\" TrustedBSD Project - support for POSIX.1e process capabilities
  29 .\"
  30 .Dd April 1, 2000
  31 .Dt CAP 3
  32 .Os FreeBSD
  33 .Sh NAME
  34 .Nm cap
  35 .Nd introduction to the POSIX.1e Capability security API
  36 .Sh SYNOPSIS
  37 .Fd #include <sys/types.h>
  38 .Fd #include <sys/capability.h>
  39 .Sh DESCRIPTION
  40 The POSIX.1e Capability interface allows processes to manipulate their
  41 capability set, subject to capability manipulation restrictions imposed
  42 by the kernel.  Using the capability API, a process may request a copy
  43 of its capability state, modify the copy of the state, and resubmit the
  44 state for use, if permitted.
  45 .Pp
  46 A variety of functions are provided for manipulating and managing
  47 process capability state and working store state:
  48 .Bl -tag -width cap_from_textXX
  49 .It Fn cap_init
  50 This function is described in
  51 .Xr cap_init 3 ,
  52 and may be used to allocate a fresh capability structure with no capability
  53 flags set.
  54 .It Fn cap_clear
  55 This function is described in
  56 .Xr cap_clear 3 ,
  57 and clears all capability flags in a capability structure.
  58 .It Fn cap_dup
  59 This function is described in
  60 .Xr cap_dup 3 ,
  61 and may be used to duplicate a capability structure.
  62 .It Fn cap_free
  63 This function is described in
  64 .Xr cap_free 3 ,
  65 and may be used to free a capability structure.
  66 .It Fn cap_from_text
  67 This function is described in
  68 .Xr cap_from_text 3 ,
  69 and may be used to convert a text-form capability to its internal
  70 representation.
  71 .It Fn cap_get_flag
  72 This function, described in
  73 .Xr cap_get_flag 3 ,
  74 allows retrieval of a capability flag value from capability state in
  75 working store.
  76 .It Fn cap_get_proc
  77 This function, described in
  78 .Xr cap_get_proc 3 ,
  79 allows retrieval of capability state for the current process.
  80 .It Fn cap_set_flag
  81 This function, described in
  82 .Xr cap_set_flag 3 ,
  83 allows setting of capability flag values in a capability structure held
  84 in the working store.
  85 .It Fn cap_set_proc
  86 This function, described in
  87 .Xr cap_set_proc 3 ,
  88 allows setting of the current process capability state.
  89 .It Fn cap_to_text
  90 This function, described in
  91 .Xr cap_to_text 3 ,
  92 converts a capability from its internal representation to one that is
  93 (more) readable by humans.
  94 .El
  95 .Pp
  96 A number of capabilities exist, each mapping to the ability to violate
  97 a particular aspect of the system policy.
  98 Each capability in a capability set has three flags, indicating the
  99 status of the capability with respect to the file or process it is
 100 associated with.
 101 .Bl -tag -width CAP_INHERITABLEXX
 102 .It Dv CAP_EFFECTIVE
 103 If true, the capability will be used as necessary during accesses by
 104 the process.
 105 .It Dv CAP_INHERITABLE
 106 If true, the capability will be passed through
 107 .Xr execve 2
 108 invocations as appropriate.
 109 .It Dv CAP_PERMITTED
 110 If true, the capability is permitted for the process.
 111 .El
 112 .Pp
 113 Capability inheritence occurs when processes invoke the
 114 .Xr exec 3
 115 call, resulting in internal invocation of the
 116 .Xr execve 2
 117 system call.
 118 At that time, a processes capabilities are re-evaluated using a set of
 119 fixed algorithms.
 120 These algorithms take into account the starting capabilities of the process
 121 and the capabilities of the file being executed.
 122 .Pp
 123 pI` = pI
 124 .Pp
 125 pP` = (fP & X) | (fI & pI)
 126 .Pp
 127 pE` = (fE & pP`)
 128 .Pp
 129 p[IPE] represent the starting processes inheritted, permitted, and
 130 effective sets.
 131 p'[IPE] represent the new inheritted, permitted, and effective sets.
 132 f[IPE] represent the file's inheritted, permitted, and effective sets.
 133 X represents a global bounding set, currently un-implemented.
 134 .Pp
 135 The following capabilities are defined and implemented in
 136 .Fx 5.0 :
 137 .Pp
 138 .Bl -tag -width CAP_MAC_RELABEL_SUBJ
 139 .It Dv CAP_CHOWN
 140 This capability overrides the restriction that a process cannot change the
 141 user ID of a file it owns, and the restriction that the group ID supplied in
 142 the
 143 .Xr chown 2
 144 function shall be equal to either the group ID or one of the supplementary
 145 group IDs of the calling process.
 146 .It Dv CAP_DAC_EXECUTE
 147 This capability overrides file mode execute access restrictions when accessing
 148 an object, and, if
 149 .Xr posix1e 3
 150 ACLs are available, this capability overrides the ACL execute access
 151 restrictions when accessing an object.
 152 .It Dv CAP_DAC_WRITE
 153 This capability overrides file mode write access restrictions when access an
 154 object, and, if
 155 .Xr posix1e 3
 156 ACLs are available, this capability also overrides the ACL write access
 157 restrictions when accessing an object.
 158 .It Dv CAP_DAC_READ_SEARCH
 159 This capability overrides file mode read and search access restrictions
 160 when accessing an object, and, if
 161 .Xr posix1e 3
 162 ACLs are available, this capability overrides the ACL read and search access
 163 restrictions when accessing an object.
 164 .It Dv CAP_FOWNER
 165 This capability overrides the requirements that the user ID associated
 166 with a process be equal to the file owner ID, execpt in the cases where the
 167 CAP_FSETID capability is applicable.
 168 In general, this capability, when effective, permits a process to perform
 169 all the functions that any file owner would have for their files.
 170 .It Dv CAP_FSETID
 171 This capability overrides the following restrictions: that the effective
 172 user ID of the calling process shall match the file owner when setting the
 173 set-user-ID (S_ISUID) and set-group-ID (S_ISGID) bits on the file; that
 174 the effective group ID or one of the supplementary group IDs of the calling
 175 process shall match the group ID of the file when setting the set-group-ID
 176 bit of the file; and that the set-user-ID and set-group-ID bits of the file
 177 mode shall be cleared upon successful return from
 178 .Xr chown 2 .
 179 .It Dv CAP_KILL
 180 Thie capability shall override the restriction that the real or effective
 181 user ID of a process sending a signal must match the real of effective user
 182 ID of the receiving process.
 183 .It Dv CAP_LINK_DIR
 184 This capability is not available on the the FreeBSD platform.
 185 On other platforms, this capabiity overrides the restriction that a process
 186 cannot create or delete a hard link to a directory.
 187 .It Dv CAP_SETFCAP
 188 This capability overrides the restriction that a process cannot
 189 set the file capability state of a file.
 190 .It Dv CAP_SETGID
 191 This capability overrides the restriction in the
 192 .Xr setgid 2
 193 function that a process cannot change its real group ID or change its
 194 effective group ID to a value other than its real group ID.
 195 .It Dv CAP_SETUID
 196 This capability overrides the restriction in the
 197 .Xr setuid 2
 198 function that a process cannot change its real user ID or change its
 199 effective user ID to a value other than the current real user ID.
 200 .It Dv CAP_MAC_DOWNGRADE
 201 This capability override the restriction that no process may downgrade
 202 the MAC label of a file.
 203 .It Dv CAP_MAC_READ
 204 This capability overrides mandatory read access restrictions when accessing
 205 objects.
 206 .It Dv CAP_MAC_RELABEL_SUBJ
 207 This capability overrides the restriction that a process may not modify
 208 its own MAC label.
 209 .It Dv CAP_MAC_UPGRADE
 210 This capability overrides the restriction that no process may upgrade the
 211 MAC label of a file.
 212 .It Dv CAP_MAC_WRITE
 213 This capability overrides the mandatory write access restrictions when
 214 accessing objects.
 215 .It Dv CAP_AUDIT_CONTROL
 216 This capability overrides the restriction that a process cannot modify
 217 audit control parameters.
 218 .It Dv CAP_AUDIT_WRITE
 219 This capability overrides the restriction that a process cannot write data
 220 into the system audit trail.
 221 .It Dv CAP_SETPCAP
 222 This capability overrides the restriction that a process cannot expand its
 223 capability set when invoking
 224 .Xr cap_set_proc 3 .
 225 .It Dv CAP_SYS_SETFFLAG
 226 This capability overrides the restriction that a process cannot manipulate
 227 the system file flags on a file system object.
 228 For portability, equivilent to
 229 .Dv CAP_LINUX_IMMUTABLE .
 230 .It Dv CAP_NET_BIND_SERVICE
 231 This capability overrides network namespace restrictions on process's
 232 using the
 233 .Xr bind 2
 234 system call.
 235 For example, this capability, when effective, can be used by a process to
 236 bind a port number below 1024 in the IPv4 or IPv6 port spaces.
 237 .It Dv CAP_NET_BROADCAST
 238 .It Dv CAP_NET_ADMIN
 239 .It Dv CAP_NET_RAW
 240 This capability overrides the restriction that a process cannot create a
 241 raw socket.
 242 .It Dv CAP_IPC_LOCK
 243 .It Dv CAP_IPC_OWNER
 244 .It Dv CAP_SYS_MODULE
 245 This capability overrides the restriction that a process cannot load or
 246 unload kernel modules.
 247 .It Dv CAP_SYS_RAWIO
 248 .It Dv CAP_SYS_CHROOT
 249 This capability overrides the restriction that a process cannot invoke the
 250 .Xr chroot 2
 251 or
 252 .Xr jail 2
 253 system calls.
 254 .It Dv CAP_SYS_PTRACE
 255 This capability overrides the restriction that a process can only invoke
 256 the
 257 .Xr ptrace 2
 258 system call to debug another process if the target process has identical
 259 real and effective user IDs.
 260 .It Dv CAP_SYS_PACCT
 261 This capability overrides the restriction that a process cannot enable,
 262 configure, or disable system process accounting.
 263 .It Dv CAP_SYS_ADMIN
 264 .It Dv CAP_SYS_BOOT
 265 This capability overrides the restriction that a process cannot invoke
 266 the
 267 .Xr boot 2
 268 system call.
 269 .It Dv CAP_SYS_NICE
 270 This capability overrides the restrictions that a process cannot use the
 271 .Xr setpriority 2
 272 system call to decrease the priority to below that of itself, or modify the
 273 priority of another process.
 274 .It Dv CAP_SYS_RESOURCE
 275 This capability overrides restrictions on how a process may modify its
 276 soft and hard resource limits.
 277 .It Dv CAP_SYS_TIME
 278 This capability overrides the restriction that a process may not modify the
 279 system date and time.
 280 .It Dv CAP_SYS_TTY_CONFIG
 281 .It Dv CAP_MKNOD
 282 This capability overrides the restriction that a process may not create
 283 device nodes.
 284 .El
 285 .Pp
 286 Documentation of the internal kernel interfaces backing these calls may
 287 be found in
 288 .Xr cap 9 .
 289 The system calls between the internal interfaces and the public library
 290 routines may change over time, and as such are not documented.  They are
 291 not intended to be called directly without going through the library.
 292 .Sh IMPLEMENTATION NOTES
 293 Support for POSIX.1e interfaces and features in
 294 .Fx
 295 is still under development at this time.
 296 .Pp
 297 POSIX.1e assigns security labels to all objects, extending the security
 298 functionality described in POSIX.1.  These additional labels provide
 299 fine-grained discretionary access control, fine-grained capabilities,
 300 and labels necessary for mandatory access control.  POSIX.2c describes
 301 a set of userland utilities for manipulating these labels.  These userland
 302 utilities are not bundled with
 303 .Fx 5.0
 304 so as to discourage their
 305 use in the short term.
 306 .\" .Sh FILES
 307 .Sh SEE ALSO
 308 .Xr cap_clear 3 ,
 309 .Xr cap_dup 3 ,
 310 .Xr cap_free 3 ,
 311 .Xr cap_get_flag 3 ,
 312 .Xr cap_get_proc 3 ,
 313 .Xr cap_init 3 ,
 314 .Xr cap_set_flag 3 ,
 315 .Xr cap_set_proc 3 ,
 316 .Xr cap 9 ,
 317 .Xr posix1e 3
 318 .Sh STANDARDS
 319 POSIX.1e is described in IEEE POSIX.1e draft 17.  Discussion
 320 of the draft continues on the cross-platform POSIX.1e implementation
 321 mailing list.  To join this list, see the
 322 .Fx
 323 POSIX.1e implementation
 324 page for more information.
 325 .Sh HISTORY
 326 Support for POSIX.1e Capabilities was developed as part of the TrustedBSD
 327 Project.
 328 POSIX.1e support was introduced in
 329 .Fx 4.0 ,
 330 and development continues.
 331 .Sh AUTHORS
 332 .An Robert N M Watson
 333 .An Ilmar S Habibulin
 334 .Sh BUGS
 335 While
 336 .Xr posix1e 3
 337 is fully implemented, supporting kernel code is not yet available in the
 338 base distribution.
 339 It is slated for inclusion prior to
 340 .Fx 5.0 .