accessrules.html (12479B)
1 <html> 2 <head> 3 <meta name="viewport" content="width=device-width, initial-scale=1.0" /> 4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> 5 <meta http-equiv="Content-Language" content="en" /> 6 <title>s6: the accessrules library interface</title> 7 <meta name="Description" content="s6: the accessrules library interface" /> 8 <meta name="Keywords" content="s6 net accessrules library libs6net unix tcp access control dns ipv4 ipv6" /> 9 <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> 10 </head> 11 <body> 12 13 <p> 14 <a href="index.html">libs6</a><br /> 15 <a href="../">s6</a><br /> 16 <a href="//skarnet.org/software/">Software</a><br /> 17 <a href="//skarnet.org/">skarnet.org</a> 18 </p> 19 20 <h1> The <tt>accessrules</tt> library interface </h1> 21 22 <p> 23 The following functions and structures are declared in the <tt>s6/accessrules.h</tt> header, 24 and implemented in the <tt>libs6.a</tt> or <tt>libs6.so</tt> library. 25 </p> 26 27 <h2> General information </h2> 28 29 <p> 30 <tt>accessrules</tt> is an access control library. It looks up 31 a key in a user-specified database, then returns a code depending on 32 whether the database allows access (in which case additional information 33 can also be returned), denies access, or does not contain the key. 34 </p> 35 36 <p> 37 <tt>accessrules</tt> has been designed to be easily extensible to any 38 database format and any key format. 39 </p> 40 41 <p> 42 Check the <tt>s6/accessrules.h</tt> header for the exact definitions. 43 </p> 44 45 <h2> Data structures </h2> 46 47 <ul> 48 <li> A <tt>s6_accessrules_result_t</tt> is a scalar that 49 can have the following values: S6_ACCESSRULES_ERROR, 50 S6_ACCESSRULES_DENY, S6_ACCESSRULES_ALLOW or S6_ACCESSRULES_NOTFOUND. </li> 51 <li> A <tt>s6_accessrules_params_t</tt> is a structure containing two 52 <a href="//skarnet.org/software/skalibs/libstddjb/stralloc.html">strallocs</a>, 53 <em>.env</em> and <em>.exec</em>, used to return data contained in the 54 database when a key has been allowed. The interpretation of this data is 55 application-defined. </li> 56 </ul> 57 58 <h2> Function types </h2> 59 60 <h3> Backend lookups </h3> 61 62 <p> 63 A <tt>s6_accessrules_backend_func_t</tt> is the type of a function 64 that takes a single key, looks it up in a database, and returns the result. 65 Namely: 66 </p> 67 68 <p> 69 <code>s6_accessrules_result_t f (char const *key, size_t keylen, void *handle, s6_accessrules_params_t *params) </code> 70 </p> 71 72 <p> 73 <em>f</em> looks up key <em>key</em> of length <em>keylen</em> in the database 74 represented by <em>handle</em> in an implementation-defined way. It returns a 75 number that says the key has been allowed, denied or not found, or an error 76 occurred. If the key has been allowed, <em>f</em> stores additional information 77 from the database into *<em>params</em>. 78 </p> 79 80 <p> 81 Two s6_accessrules_backend_func_t functions are natively implemented: 82 </p> 83 84 <ul> 85 <li> <tt>s6_accessrules_backend_fs</tt> takes a <tt>char const *</tt> 86 <em>handle</em> and interprets it as a base directory to look up <em>key</em> 87 under, in the format understood by 88 <a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a>. </li> 89 <li> <tt>s6_accessrules_backend_cdb</tt> takes a <tt>struct cdb *</tt> 90 <em>handle</em> and looks up <em>key</em> in the 91 <a href="https://cr.yp.to/cdb.html">CDB</a> it points to. <em>handle</em> must 92 already be mapped to a CDB file. Such a file can be built with the 93 <a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a> 94 utility. </li> 95 </ul> 96 97 <h3> Frontend key checking </h3> 98 99 <p> 100 A <tt>s6_accessrules_keycheck_func_t</tt> is the type of a function that 101 takes a user-level key, makes a list of corresponding backend-level keys and 102 calls a <tt>s6_accessrules_backend_func_t</tt> function until it finds 103 a match. Namely: 104 </p> 105 106 <p> 107 <code>s6_accessrules_result_t f (void const *key, void *handle, s6_accessrules_params_t *params, s6_accessrules_backend_func_t *backend) </code> 108 </p> 109 110 <p> 111 <em>f</em> derives a list of low-level keys to check from <em>key</em>. 112 Then, for each key <em>k</em> of length <em>klen</em> in this list, it calls 113 <tt>(*backend)(k, klen, handle, params)</tt>, returning *<em>backend</em>'s result if it 114 is not S6_ACCESSRULES_NOTFOUND. If no match can be found in the whole list, 115 <em>f</em> finally returns S6_ACCESSRULES_NOTFOUND. 116 </p> 117 118 <p> 119 Five s6_accessrules_keycheck_func_t functions are natively implemented: 120 </p> 121 122 <ul> 123 <li> 124 <a name="uidgid" /> 125 <tt>s6_accessrules_keycheck_uidgid</tt> interprets <em>key</em> as a 126 pointer to a structure containing an uid <em>u</em> and a gid <em>g</em>. 127 The following checks are performed, in this order (i.e. subsequent 128 checks are not performed if a match is found): 129 <ul> 130 <li> If <em>u</em> is equal to the effective uid of the process, look 131 for a <tt>uid/self</tt> match. </li> 132 <li> Look for a <tt>uid/<em>u</em></tt> match. </li> 133 <li> If <em>g</em> is equal to the effective gid of the process, look 134 for a <tt>gid/self</tt> match. </li> 135 <li> Look for a <tt>gid/<em>g</em></tt> match. </li> 136 <li> Look for a <tt>uid/default</tt> match. </li> 137 </ul> </li> 138 <li> 139 <a name="reversedns" /> 140 <tt>s6_accessrules_keycheck_reversedns</tt> interprets <em>key</em> 141 as a string containing a FQDN. Then for each suffix <em>k</em> of <em>key</em>, 142 starting with <em>key</em> itself and ending with <em>key</em>'s TLD, 143 it looks up <tt>reversedns/<em>k</em></tt>. The final dot is excluded from 144 <em>k</em>. If no match can be found, the function checks <tt>reversedns/@</tt> 145 and returns the result. For instance, if <em>key</em> is "foo.bar.com", 146 the following strings are looked up, in this order: 147 <ul> 148 <li> reversedns/foo.bar.com </li> 149 <li> reversedns/bar.com </li> 150 <li> reversedns/com </li> 151 <li> reversedns/@ </li> 152 </ul> </li> 153 <li> 154 <a name="ip4" /> 155 <tt>s6_accessrules_keycheck_ip4</tt> interprets <em>key</em> as 156 4 network-byte-order characters containing an IPv4 address. Then for each 157 netmask <em>mask</em> from 32 to 0, it constructs the IPv4 network 158 prefix <em>addr</em> corresponding to that address, and looks up 159 <tt>ip4/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em> 160 is "\300\250\001\007", representing the 192.168.1.7 address, the following 161 strings are looked up, in this order: 162 <ul> 163 <li> ip4/192.168.1.7_32 </li> 164 <li> ip4/192.168.1.6_31 </li> 165 <li> ip4/192.168.1.4_30 </li> 166 <li> ip4/192.168.1.0_29 </li> 167 <li> ip4/192.168.0.0_28 </li> 168 <li> ip4/192.168.0.0_27 </li> 169 </ul> 170 and so on, down to: 171 <ul> 172 <li> ip4/192.0.0.0_3 </li> 173 <li> ip4/192.0.0.0_2 </li> 174 <li> ip4/128.0.0.0_1 </li> 175 <li> ip4/0.0.0.0_0 </li> 176 </ul> 177 Note that the <tt>ip4/0.0.0.0_0</tt> string is a catch-all key that 178 matches everything. </li> 179 <li> 180 <a name="ip6" /> 181 <tt>s6_accessrules_keycheck_ip6</tt> interprets <em>key</em> as 182 16 network-byte-order characters containing an IPv6 address. Then for each 183 netmask <em>mask</em> from 128 to 0, it constructs the IPv6 network 184 prefix <em>addr</em> corresponding to that address, 185 <strong>in canonical form</strong>, 186 and looks up 187 <tt>ip6/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em> 188 is "*\0\024P@\002\b\003\0\0\0\0\0\0\020\006", representing the 189 2a00:1450:4002:803::1006 address, the following 190 strings are looked up, in this order: 191 <ul> 192 <li> ip6/2a00:1450:4002:803::1006_128 </li> 193 <li> ip6/2a00:1450:4002:803::1006_127 </li> 194 <li> ip6/2a00:1450:4002:803::1004_126 </li> 195 <li> ip6/2a00:1450:4002:803::1000_125 </li> 196 <li> ip6/2a00:1450:4002:803::1000_124 </li> 197 <li> ip6/2a00:1450:4002:803::1000_123 </li> 198 <li> ip6/2a00:1450:4002:803::1000_122 </li> 199 <li> ip6/2a00:1450:4002:803::1000_121 </li> 200 <li> ip6/2a00:1450:4002:803::1000_120 </li> 201 <li> ip6/2a00:1450:4002:803::1000_119 </li> 202 <li> ip6/2a00:1450:4002:803::1000_118 </li> 203 <li> ip6/2a00:1450:4002:803::1000_117 </li> 204 <li> ip6/2a00:1450:4002:803::1000_116 </li> 205 <li> ip6/2a00:1450:4002:803::1000_115 </li> 206 <li> ip6/2a00:1450:4002:803::1000_114 </li> 207 <li> ip6/2a00:1450:4002:803::1000_113 </li> 208 <li> ip6/2a00:1450:4002:803::_112 </li> 209 <li> ip6/2a00:1450:4002:803::_111 </li> 210 </ul> 211 and so on, down to: 212 <ul> 213 <li> ip6/2a00::_11 </li> 214 <li> ip6/2800::_10 </li> 215 <li> ip6/2800::_9 </li> 216 <li> ip6/2000::_8 </li> 217 <li> ip6/2000::_7 </li> 218 <li> ip6/2000::_6 </li> 219 <li> ip6/2000::_5 </li> 220 <li> ip6/2000::_4 </li> 221 <li> ip6/2000::_3 </li> 222 <li> ip6/::_2 </li> 223 <li> ip6/::_1 </li> 224 <li> ip6/::_0 </li> 225 </ul> 226 Note that the <tt>ip6/::_0</tt> string is a catch-all key that 227 matches everything. </li> 228 <li> 229 <a name="ip46" /> 230 <tt>s6_accessrules_keycheck_ip46</tt> interprets <em>key</em> as a pointer to an 231 <a href="//skarnet.org/software/skalibs/libstddjb/ip46.html">ip46_t</a>, and 232 behaves either as s6_accessrules_keycheck_ip6 or s6_accessrules_keycheck_ip4, 233 depending on the type of address *<em>key</em> contains. </li> 234 </ul> 235 236 <h2> Ready-to-use functions </h2> 237 238 Those functions are mostly macros; they're built by associating a frontend 239 function with a backend function. 240 241 <p> 242 <code> s6_accessrules_result_t s6_accessrules_uidgid_cdb 243 (uid_t u, gid_t g, struct cdb *c, 244 s6_accessrules_params_t *params) </code> <br /> 245 Checks the *<em>c</em> CDB database for an authorization for uid <em>u</em> 246 and gid <em>g</em>. If the result is S6_ACCESSRULES_ALLOW, additional 247 information may be stored into <em>params</em>. 248 </p> 249 250 <p> 251 <code> s6_accessrules_result_t s6_accessrules_uidgid_fs 252 (uid_t u, gid_t g, char const *dir, 253 s6_accessrules_params_t *params) </code> <br /> 254 Checks the <em>dir</em> base directory for an authorization for uid <em>u</em> 255 and gid <em>g</em>. If the result is S6_ACCESSRULES_ALLOW, additional 256 information may be stored into <em>params</em>. 257 </p> 258 259 <p> 260 <code> s6_accessrules_result_t s6_accessrules_reversedns_cdb 261 (char const *name, struct cdb *c, 262 s6_accessrules_params_t *params) </code> <br /> 263 Checks the *<em>c</em> CDB database for an authorization for the 264 <em>name</em> FQDN. If the result is S6_ACCESSRULES_ALLOW, additional 265 information may be stored into <em>params</em>. 266 </p> 267 268 <p> 269 <code> s6_accessrules_result_t s6_accessrules_reversedns_fs 270 (char const *name, char const *dir, 271 s6_accessrules_params_t *params) </code> <br /> 272 Checks the <em>dir</em> base directory for an authorization for the 273 <em>name</em> FQDN. If the result is S6_ACCESSRULES_ALLOW, additional 274 information may be stored into <em>params</em>. 275 </p> 276 277 <p> 278 <code> s6_accessrules_result_t s6_accessrules_ip4_cdb 279 (char const *ip4, struct cdb *c, 280 s6_accessrules_params_t *params) </code> <br /> 281 Checks the *<em>c</em> CDB database for an authorization for the 282 <em>ip4</em> IPv4 address (4 network byte order characters). 283 If the result is S6_ACCESSRULES_ALLOW, additional 284 information may be stored into <em>params</em>. 285 </p> 286 287 <p> 288 <code> s6_accessrules_result_t s6_accessrules_ip4_fs 289 (char const *ip4, char const *dir, 290 s6_accessrules_params_t *params) </code> <br /> 291 Checks the <em>dir</em> base directory for an authorization for the 292 <em>ip4</em> IPv4 address (4 network byte order characters). 293 If the result is S6_ACCESSRULES_ALLOW, additional 294 information may be stored into <em>params</em>. 295 </p> 296 297 <p> 298 <code> s6_accessrules_result_t s6_accessrules_ip6_cdb 299 (char const *ip6, struct cdb *c, 300 s6_accessrules_params_t *params) </code> <br /> 301 Checks the *<em>c</em> CDB database for an authorization for the 302 <em>ip6</em> IPv6 address (16 network byte order characters). 303 If the result is S6_ACCESSRULES_ALLOW, additional 304 information may be stored into <em>params</em>. 305 </p> 306 307 <p> 308 <code> s6_accessrules_result_t s6_accessrules_ip6_fs 309 (char const *ip6, char const *dir, 310 s6_accessrules_params_t *params) </code> <br /> 311 Checks the <em>dir</em> base directory for an authorization for the 312 <em>ip6</em> IPv6 address (16 network byte order characters). 313 If the result is S6_ACCESSRULES_ALLOW, additional 314 information may be stored into <em>params</em>. 315 </p> 316 317 <p> 318 <code> s6_accessrules_result_t s6_accessrules_ip46_cdb 319 (ip46_t *ip, struct cdb *c, 320 s6_accessrules_params_t *params) </code> <br /> 321 Checks the *<em>c</em> CDB database for an authorization for the 322 <em>ip</em> IP address. 323 If the result is S6_ACCESSRULES_ALLOW, additional 324 information may be stored into <em>params</em>. 325 </p> 326 327 <p> 328 <code> s6_accessrules_result_t s6_accessrules_ip46_fs 329 (ip46_t const *ip, char const *dir, 330 s6_accessrules_params_t *params) </code> <br /> 331 Checks the <em>dir</em> base directory for an authorization for the 332 <em>ip</em> IP address. 333 If the result is S6_ACCESSRULES_ALLOW, additional 334 information may be stored into <em>params</em>. 335 </p> 336 337 </body> 338 </html>