lib/libcapsicum/capsicum_helpers.3

   1 .\" Copyright (c) 2016 Mariusz Zaborski <oshogbo@FreeBSD.org>
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd January 2, 2020
  26 .Dt CAPSICUM_HELPERS 3
  27 .Os
  28 .Sh NAME
  29 .Nm caph_limit_stream ,
  30 .Nm caph_limit_stdin ,
  31 .Nm caph_limit_stderr ,
  32 .Nm caph_limit_stdout ,
  33 .Nm caph_limit_stdio ,
  34 .Nm caph_stream_rights ,
  35 .Nm caph_cache_tzdata ,
  36 .Nm caph_cache_catpages ,
  37 .Nm caph_enter ,
  38 .Nm caph_enter_casper ,
  39 .Nm caph_rights_limit ,
  40 .Nm caph_ioctls_limit ,
  41 .Nm caph_fcntls_limit
  42 .Nd "set of the capsicum helpers, part of the libcapsicum"
  43 .Sh LIBRARY
  44 .Lb libcapsicum
  45 .Sh SYNOPSIS
  46 .In capsicum_helpers.h
  47 .Ft int
  48 .Fn caph_enter "void"
  49 .Ft int
  50 .Fn caph_enter_casper "void"
  51 .Ft int
  52 .Fn caph_rights_limit "int fd" "const cap_rights_t *rights"
  53 .Ft int
  54 .Fn caph_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds"
  55 .Ft int
  56 .Fn caph_fcntls_limit "int fd" "uint32_t fcntlrights"
  57 .Ft int
  58 .Fn caph_limit_stream "int fd" "int flags"
  59 .Ft int
  60 .Fn caph_limit_stdin "void"
  61 .Ft int
  62 .Fn caph_limit_stderr "void"
  63 .Ft int
  64 .Fn caph_limit_stdout "void"
  65 .Ft int
  66 .Fn caph_limit_stdio "void"
  67 .Ft void
  68 .Fn caph_stream_rights "cap_rights_t *" "int flags"
  69 .Ft void
  70 .Fn caph_cache_tzdata "void"
  71 .Ft void
  72 .Fn caph_cache_catpages "void"
  73 .Sh DESCRIPTION
  74 The
  75 .Nm caph_enter ,
  76 .Nm caph_rights_limit ,
  77 .Nm caph_ioctls_limit
  78 and
  79 .Nm caph_fcntls_limit
  80 are respectively equivalent to
  81 .Xr cap_enter 2 ,
  82 .Xr cap_rights_limit 2 ,
  83 .Xr cap_ioctls_limit 2
  84 and
  85 .Xr cap_fcntls_limit 2 ,
  86 it returns success when the kernel is built without support of the capability
  87 mode.
  88 .Pp
  89 The
  90 .Nm caph_enter_casper
  91 is equivalent to the
  92 .Nm caph_enter
  93 it returns success when the system is built without Casper support.
  94 .Pp
  95 The
  96 .Nm capsicum helpers
  97 are a set of a inline functions which simplify modifying programs to use
  98 Capsicum.
  99 The goal is to reduce duplicated code patterns.
 100 The
 101 .Nm capsicum helpers
 102 are part of
 103 .Nm libcapsicum
 104 but there is no need to link to the library.
 105 .Pp
 106 .Fn caph_limit_stream
 107 restricts capabilities on
 108 .Fa fd
 109 to only those needed by POSIX stream objects (that is, FILEs).
 110 .Pp
 111 These flags can be provided:
 112 .Pp
 113 .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
 114 .It Dv CAPH_IGNORE_EBADF
 115 Do not return an error if file descriptor is invalid.
 116 .It Dv CAPH_READ
 117 Set CAP_READ on limited descriptor.
 118 .It Dv CAPH_WRITE
 119 Set CAP_WRITE on limited descriptor.
 120 .El
 121 .Pp
 122 .Fn caph_limit_stdin ,
 123 .Fn caph_limit_stderr
 124 and
 125 .Fn caph_limit_stdout
 126 limit standard descriptors using the
 127 .Nm caph_limit_stream
 128 function.
 129 .Pp
 130 .Fn caph_limit_stdio
 131 limits stdin, stderr and stdout.
 132 .Pp
 133 .Nm caph_stream_rights
 134 may be used to initialize
 135 .Fa rights
 136 with the same rights that a stream would be limited to, as if
 137 .Fn caph_limit_stream
 138 had been invoked using the same
 139 .Fa flags .
 140 .Pp
 141 .Fn caph_cache_tzdata
 142 precaches all timezone data needed to use
 143 .Li libc
 144 local time functions.
 145 .Pp
 146 .Fn caph_cache_catpages
 147 caches Native Language Support (NLS) data.
 148 NLS data is used for localized error printing by
 149 .Xr strerror 3
 150 and
 151 .Xr err 3 ,
 152 among others.
 153 .Ed
 154 .Sh SEE ALSO
 155 .Xr cap_enter 2 ,
 156 .Xr cap_rights_limit 2 ,
 157 .Xr rights 4