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