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 .\" $FreeBSD$
  26 .\"
  27 .Dd January 2, 2020
  28 .Dt CAPSICUM_HELPERS 3
  29 .Os
  30 .Sh NAME
  31 .Nm caph_limit_stream ,
  32 .Nm caph_limit_stdin ,
  33 .Nm caph_limit_stderr ,
  34 .Nm caph_limit_stdout ,
  35 .Nm caph_limit_stdio ,
  36 .Nm caph_stream_rights ,
  37 .Nm caph_cache_tzdata ,
  38 .Nm caph_cache_catpages ,
  39 .Nm caph_enter ,
  40 .Nm caph_enter_casper ,
  41 .Nm caph_rights_limit ,
  42 .Nm caph_ioctls_limit ,
  43 .Nm caph_fcntls_limit
  44 .Nd "set of the capsicum helpers, part of the libcapsicum"
  45 .Sh LIBRARY
  46 .Lb libcapsicum
  47 .Sh SYNOPSIS
  48 .In capsicum_helpers.h
  49 .Ft int
  50 .Fn caph_enter "void"
  51 .Ft int
  52 .Fn caph_enter_casper "void"
  53 .Ft int
  54 .Fn caph_rights_limit "int fd" "const cap_rights_t *rights"
  55 .Ft int
  56 .Fn caph_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds"
  57 .Ft int
  58 .Fn caph_fcntls_limit "int fd" "uint32_t fcntlrights"
  59 .Ft int
  60 .Fn caph_limit_stream "int fd" "int flags"
  61 .Ft int
  62 .Fn caph_limit_stdin "void"
  63 .Ft int
  64 .Fn caph_limit_stderr "void"
  65 .Ft int
  66 .Fn caph_limit_stdout "void"
  67 .Ft int
  68 .Fn caph_limit_stdio "void"
  69 .Ft void
  70 .Fn caph_stream_rights "cap_rights_t *" "int flags"
  71 .Ft void
  72 .Fn caph_cache_tzdata "void"
  73 .Ft void
  74 .Fn caph_cache_catpages "void"
  75 .Sh DESCRIPTION
  76 The
  77 .Nm caph_enter ,
  78 .Nm caph_rights_limit ,
  79 .Nm caph_ioctls_limit
  80 and
  81 .Nm caph_fcntls_limit
  82 are respectively equivalent to
  83 .Xr cap_enter 2 ,
  84 .Xr cap_rights_limit 2 ,
  85 .Xr cap_ioctls_limit 2
  86 and
  87 .Xr cap_fcntls_limit 2 ,
  88 it returns success when the kernel is built without support of the capability
  89 mode.
  90 .Pp
  91 The
  92 .Nm caph_enter_casper
  93 is equivalent to the
  94 .Nm caph_enter
  95 it returns success when the system is built without Casper support.
  96 .Pp
  97 The
  98 .Nm capsicum helpers
  99 are a set of a inline functions which simplify modifying programs to use
 100 Capsicum.
 101 The goal is to reduce duplicated code patterns.
 102 The
 103 .Nm capsicum helpers
 104 are part of
 105 .Nm libcapsicum
 106 but there is no need to link to the library.
 107 .Pp
 108 .Fn caph_limit_stream
 109 restricts capabilities on
 110 .Fa fd
 111 to only those needed by POSIX stream objects (that is, FILEs).
 112 .Pp
 113 These flags can be provided:
 114 .Pp
 115 .Bl -tag -width "CAPH_IGNORE_EBADF" -compact -offset indent
 116 .It Dv CAPH_IGNORE_EBADF
 117 Do not return an error if file descriptor is invalid.
 118 .It Dv CAPH_READ
 119 Set CAP_READ on limited descriptor.
 120 .It Dv CAPH_WRITE
 121 Set CAP_WRITE on limited descriptor.
 122 .El
 123 .Pp
 124 .Fn caph_limit_stdin ,
 125 .Fn caph_limit_stderr
 126 and
 127 .Fn caph_limit_stdout
 128 limit standard descriptors using the
 129 .Nm caph_limit_stream
 130 function.
 131 .Pp
 132 .Fn caph_limit_stdio
 133 limits stdin, stderr and stdout.
 134 .Pp
 135 .Nm caph_stream_rights
 136 may be used to initialize
 137 .Fa rights
 138 with the same rights that a stream would be limited to, as if
 139 .Fn caph_limit_stream
 140 had been invoked using the same
 141 .Fa flags .
 142 .Pp
 143 .Fn caph_cache_tzdata
 144 precaches all timezone data needed to use
 145 .Li libc
 146 local time functions.
 147 .Pp
 148 .Fn caph_cache_catpages
 149 caches Native Language Support (NLS) data.
 150 NLS data is used for localized error printing by
 151 .Xr strerror 3
 152 and
 153 .Xr err 3 ,
 154 among others.
 155 .Ed
 156 .Sh SEE ALSO
 157 .Xr cap_enter 2 ,
 158 .Xr cap_rights_limit 2 ,
 159 .Xr rights 4