lib/libc/sys/cap_ioctls_limit.2

   1 .\"
   2 .\" Copyright (c) 2012 The FreeBSD Foundation
   3 .\" All rights reserved.
   4 .\"
   5 .\" This documentation was written by Pawel Jakub Dawidek under sponsorship
   6 .\" the FreeBSD Foundation.
   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_IOCTLS_LIMIT 2
  33 .Os
  34 .Sh NAME
  35 .Nm cap_ioctls_limit ,
  36 .Nm cap_ioctls_get
  37 .Nd manage allowed ioctl commands
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In sys/capsicum.h
  42 .Ft int
  43 .Fn cap_ioctls_limit "int fd" "const unsigned long *cmds" "size_t ncmds"
  44 .Ft ssize_t
  45 .Fn cap_ioctls_get "int fd" "unsigned long *cmds" "size_t maxcmds"
  46 .Sh DESCRIPTION
  47 If a file descriptor is granted the
  48 .Dv CAP_IOCTL
  49 capability right, the list of allowed
  50 .Xr ioctl 2
  51 commands can be selectively reduced (but never expanded) with the
  52 .Fn cap_ioctls_limit
  53 system call.
  54 The
  55 .Fa cmds
  56 argument is an array of
  57 .Xr ioctl 2
  58 commands and the
  59 .Fa ncmds
  60 argument specifies the number of elements in the array.
  61 There can be up to
  62 .Va 256
  63 elements in the array.
  64 Including an element that has been previously revoked will generate an error.
  65 After a successful call only those listed in the array may be used.
  66 .Pp
  67 The list of allowed ioctl commands for a given file descriptor can be obtained
  68 with the
  69 .Fn cap_ioctls_get
  70 system call.
  71 The
  72 .Fa cmds
  73 argument points at memory that can hold up to
  74 .Fa maxcmds
  75 values.
  76 The function populates the provided buffer with up to
  77 .Fa maxcmds
  78 elements, but always returns the total number of ioctl commands allowed for the
  79 given file descriptor.
  80 The total number of ioctls commands for the given file descriptor can be
  81 obtained by passing
  82 .Dv NULL as the
  83 .Fa cmds
  84 argument and
  85 .Va 0
  86 as the
  87 .Fa maxcmds
  88 argument.
  89 If all ioctl commands are allowed
  90 .Dv ( CAP_IOCTL
  91 capability right is assigned to the file descriptor and the
  92 .Fn cap_ioctls_limit
  93 system call was never called for this file descriptor), the
  94 .Fn cap_ioctls_get
  95 system call will return
  96 .Dv CAP_IOCTLS_ALL
  97 and will not modify the buffer pointed to by the
  98 .Fa cmds
  99 argument.
 100 .Sh RETURN VALUES
 101 .Rv -std cap_ioctls_limit
 102 .Pp
 103 The
 104 .Fn cap_ioctls_get
 105 function, if successful, returns the total number of allowed ioctl commands or
 106 the value
 107 .Dv CAP_IOCTLS_ALL
 108 if all ioctls commands are allowed.
 109 On failure the value
 110 .Va -1
 111 is returned and the global variable errno is set to indicate the error.
 112 .Sh ERRORS
 113 .Fn cap_ioctls_limit
 114 succeeds unless:
 115 .Bl -tag -width Er
 116 .It Bq Er EBADF
 117 The
 118 .Fa fd
 119 argument is not a valid descriptor.
 120 .It Bq Er EFAULT
 121 The
 122 .Fa cmds
 123 argument points at an invalid address.
 124 .It Bq Er EINVAL
 125 The
 126 .Fa ncmds
 127 argument is greater than
 128 .Va 256 .
 129 .It Bq Er ENOTCAPABLE
 130 .Fa cmds
 131 would expand the list of allowed
 132 .Xr ioctl 2
 133 commands.
 134 .El
 135 .Pp
 136 .Fn cap_ioctls_get
 137 succeeds unless:
 138 .Bl -tag -width Er
 139 .It Bq Er EBADF
 140 The
 141 .Fa fd
 142 argument is not a valid descriptor.
 143 .It Bq Er EFAULT
 144 The
 145 .Fa cmds
 146 argument points at invalid address.
 147 .El
 148 .Sh SEE ALSO
 149 .Xr cap_fcntls_limit 2 ,
 150 .Xr cap_rights_limit 2 ,
 151 .Xr ioctl 2
 152 .Sh HISTORY
 153 The
 154 .Fn cap_ioctls_get
 155 and
 156 .Fn cap_ioctls_limit
 157 system calls first appeared in
 158 .Fx 8.3 .
 159 Support for capabilities and capabilities mode was developed as part of the
 160 .Tn TrustedBSD
 161 Project.
 162 .Sh AUTHORS
 163 This function was created by
 164 .An Pawel Jakub Dawidek Aq Mt pawel@dawidek.net
 165 under sponsorship of the FreeBSD Foundation.