Initial commit

author: Laurent Bercot <ska-skaware@skarnet.org> 2014-12-15 23:08:59 +0000
committer: Laurent Bercot <ska-skaware@skarnet.org> 2014-12-15 23:08:59 +0000
commit: e0fc82203d677a6f1e808e9a1a46176c109d89be (patch)
tree: e9609209b755e3f7a8480aea86601ffe9d4ca540 /doc/libs6net
download: s6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz
3 files changed, 518 insertions, 0 deletions
diff --git a/doc/libs6net/accessrules.html b/doc/libs6net/accessrules.html
new file mode 100644
index 0000000..ea996b7
--- /dev/null
+++ b/doc/libs6net/accessrules.html
@@ -0,0 +1,331 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the accessrules library interface</title>
+    <meta name="Description" content="s6-networking: the accessrules library interface" />
+    <meta name="Keywords" content="s6-networking net accessrules library libs6net unix tcp access control dns ipv4 ipv6" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libs6net</a><br />
+<a href="../">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>accessrules</tt> library interface </h1>
+
+<p>
+ The following functions and structures are declared in the <tt>s6-networking/accessrules.h</tt> header,
+and implemented in the <tt>libs6net.a</tt> or <tt>libs6net.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>s6net_accessrules</tt> is an access control library. It looks up
+a key in a user-specified database, then returns a code depending on
+whether the database allows access (in which case additional information
+can also be returned), denies access, or does not contain the key.
+</p>
+
+<p>
+ <tt>accessrules</tt> has been designed to be easily extensible to any
+database format and any key format.
+</p>
+
+<p>
+ Check the <tt>s6-networking/accessrules.h</tt> header for the exact definitions.
+</p>
+
+<h2> Data structures </h2>
+
+<ul>
+ <li> A <tt>s6net_accessrules_result_t</tt> is a scalar that
+can have the following values: S6NET_ACCESSRULES_ERROR,
+S6NET_ACCESSRULES_DENY, S6NET_ACCESSRULES_ALLOW or S6NET_ACCESSRULES_NOTFOUND. </li>
+ <li> A <tt>s6net_accessrules_params_t</tt> is a structure containing two
+<a href="http://skarnet.org/software/skalibs/libstddjb/stralloc.html">strallocs</a>,
+<em>.env</em> and <em>.exec</em>, used to return data contained in the
+database when a key has been allowed. The interpretation of this data is
+application-defined. </li>
+</ul>
+
+<h2> Function types </h2>
+
+<h3> Backend lookups </h3>
+
+<p>
+ A <tt>s6net_accessrules_backend_func_t</tt> is the type of a function
+that takes a single key, looks it up in a database, and returns the result.
+Namely:
+</p>
+
+<p>
+<code>s6net_accessrules_result_t f (char const *key, unsigned int keylen, void *handle, s6net_accessrules_params_t *params) </code>
+</p>
+
+<p>
+ <em>f</em> looks up key <em>key</em> of length <em>keylen</em> in the database
+represented by <em>handle</em> in an implementation-defined way. It returns a
+number that says the key has been allowed, denied or not found, or an error
+occurred. If the key has been allowed, <em>f</em> stores additional information
+from the database into *<em>params</em>.
+</p>
+
+<p>
+ Two s6net_accessrules_backend_func_t functions are natively implemented:
+</p>
+
+<ul>
+ <li> <tt>s6net_accessrules_backend_fs</tt> takes a <tt>char const *</tt>
+<em>handle</em> and interprets it as a base directory to look up <em>key</em>
+under, in the format understood by
+<a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a>. </li>
+ <li> <tt>s6net_accessrules_backend_cdb</tt> takes a <tt>struct cdb *</tt>
+<em>handle</em> and looks up <em>key</em> in the
+<a href="http://cr.yp.to/cdb.html">CDB</a> it points to. <em>handle</em> must
+already be mapped to a CDB file. Such a file can be built with the
+<a href="../s6-accessrules-cdb-from-fs.html">s6-accessrules-cdb-from-fs</a>
+utility. </li>
+</ul>
+
+<h3> Frontend key checking </h3>
+
+<p>
+ A <tt>s6net_accessrules_keycheck_func_t</tt> is the type of a function that
+takes a user-level key, makes a list of corresponding backend-level keys and
+calls a <tt>s6net_accessrules_backend_func_t</tt> function until it finds
+a match. Namely:
+</p>
+
+<p>
+<code>s6net_accessrules_result_t f (void const *key, void *handle, s6net_accessrules_params_t *params, s6net_accessrules_backend_func_t *backend) </code>
+</p>
+
+<p>
+ <em>f</em> derives a list of low-level keys to check from <em>key</em>.
+Then, for each key <em>k</em> of length <em>klen</em> in this list, it calls
+<tt>(*backend)(k, klen, handle, params)</tt>, returning *<em>backend</em>'s result if it
+is not S6NET_ACCESSRULES_NOTFOUND. If no match can be found in the whole list,
+<em>f</em> finally returns S6NET_ACCESSRULES_NOTFOUND.
+</p>
+
+<p>
+ Five s6net_accessrules_keycheck_func_t functions are natively implemented:
+</p>
+
+<ul>
+ <li>
+<a name="uidgid" />
+ <tt>s6net_accessrules_keycheck_uidgid</tt> interprets <em>key</em> as a
+<a href="http://skarnet.org/software/skalibs/libstddjb/">diuint</a>, i.e. a
+structure containing two unsigned ints. The first one is interpreted as an
+uid <em>u</em>, the second one as a gid <em>g</em>. The function first looks
+for a <tt>uid/<em>u</em></tt> match; if it cannot find one, it looks for a
+<tt>gid/<em>g</em></tt> match. If it cannot find one either, it checks
+<tt>uid/default</tt> and returns the result. </li>
+ <li>
+<a name="reversedns" />
+ <tt>s6net_accessrules_keycheck_reversedns</tt> interprets <em>key</em>
+as a string containing a FQDN. Then for each suffix <em>k</em> of <em>key</em>,
+starting with <em>key</em> itself and ending with <em>key</em>'s TLD,
+it looks up <tt>reversedns/<em>k</em></tt>. The final dot is excluded from
+<em>k</em>. If no match can be found, the function checks <tt>reversedns/@</tt>
+and returns the result. For instance, if <em>key</em> is "foo.bar.com",
+the following strings are looked up, in that order:
+  <ul>
+   <li> reversedns/foo.bar.com </li>
+   <li> reversedns/bar.com </li>
+   <li> reversedns/com </li>
+   <li> reversedns/@ </li>
+  </ul> </li>
+ <li>
+<a name="ip4" />
+ <tt>s6net_accessrules_keycheck_ip4</tt> interprets <em>key</em> as
+4 network-byte-order characters containing an IPv4 address. Then for each
+netmask <em>mask</em> from 32 to 0, it constructs the IPv4 network
+prefix <em>addr</em> corresponding to that address, and looks up
+<tt>ip4/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em>
+is "\300\250\001\007", representing the 192.168.1.7 address, the following
+strings are looked up, in that order:
+ <ul>
+  <li> ip4/192.168.1.7_32 </li>
+  <li> ip4/192.168.1.6_31 </li>
+  <li> ip4/192.168.1.4_30 </li>
+  <li> ip4/192.168.1.0_29 </li>
+  <li> ip4/192.168.0.0_28 </li>
+  <li> ip4/192.168.0.0_27 </li>
+ </ul>
+ and so on, down to:
+ <ul>
+  <li> ip4/192.0.0.0_3 </li>
+  <li> ip4/192.0.0.0_2 </li>
+  <li> ip4/128.0.0.0_1 </li>
+  <li> ip4/0.0.0.0_0 </li>
+ </ul>
+ Note that the <tt>ip4/0.0.0.0_0</tt> string is a catch-all key that
+matches everything. </li>
+ <li>
+<a name="ip6" />
+ <tt>s6net_accessrules_keycheck_ip6</tt> interprets <em>key</em> as
+16 network-byte-order characters containing an IPv6 address. Then for each
+netmask <em>mask</em> from 128 to 0, it constructs the IPv6 network
+prefix <em>addr</em> corresponding to that address,
+<strong>in canonical form</strong>,
+and looks up
+<tt>ip6/<em>addr</em>_<em>mask</em></tt>. For instance, if <em>key</em>
+is "*\0\024P@\002\b\003\0\0\0\0\0\0\020\006", representing the
+2a00:1450:4002:803::1006 address, the following
+strings are looked up, in that order:
+ <ul>
+  <li> ip6/2a00:1450:4002:803::1006_128 </li>
+  <li> ip6/2a00:1450:4002:803::1006_127 </li>
+  <li> ip6/2a00:1450:4002:803::1004_126 </li>
+  <li> ip6/2a00:1450:4002:803::1000_125 </li>
+  <li> ip6/2a00:1450:4002:803::1000_124 </li>
+  <li> ip6/2a00:1450:4002:803::1000_123 </li>
+  <li> ip6/2a00:1450:4002:803::1000_122 </li>
+  <li> ip6/2a00:1450:4002:803::1000_121 </li>
+  <li> ip6/2a00:1450:4002:803::1000_120 </li>
+  <li> ip6/2a00:1450:4002:803::1000_119 </li>
+  <li> ip6/2a00:1450:4002:803::1000_118 </li>
+  <li> ip6/2a00:1450:4002:803::1000_117 </li>
+  <li> ip6/2a00:1450:4002:803::1000_116 </li>
+  <li> ip6/2a00:1450:4002:803::1000_115 </li>
+  <li> ip6/2a00:1450:4002:803::1000_114 </li>
+  <li> ip6/2a00:1450:4002:803::1000_113 </li>
+  <li> ip6/2a00:1450:4002:803::_112 </li>
+  <li> ip6/2a00:1450:4002:803::_111 </li>
+ </ul>
+ and so on, down to:
+ <ul>
+  <li> ip6/2a00::_11 </li>
+  <li> ip6/2800::_10 </li>
+  <li> ip6/2800::_9 </li>
+  <li> ip6/2000::_8 </li>
+  <li> ip6/2000::_7 </li>
+  <li> ip6/2000::_6 </li>
+  <li> ip6/2000::_5 </li>
+  <li> ip6/2000::_4 </li>
+  <li> ip6/2000::_3 </li>
+  <li> ip6/::_2 </li>
+  <li> ip6/::_1 </li>
+  <li> ip6/::_0 </li>
+ </ul>
+ Note that the <tt>ip6/::_0</tt> string is a catch-all key that
+matches everything. </li>
+ <li>
+<a name="ip46" />
+ <tt>s6net_accessrules_keycheck_ip46</tt> interprets <em>key</em> as a pointer to an
+<a href="http://skarnet.org/software/skalibs/libstddjb/ip46.html">ip46_t</a>, and
+behaves either as s6net_accessrules_keycheck_ip6 or s6net_accessrules_keycheck_ip4,
+depending on the type of address *<em>key</em> contains. </li>
+</ul>
+
+<h2> Ready-to-use functions </h2>
+
+ Those functions are mostly macros; they're built by associating a frontend
+function with a backend function.
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_uidgid_cdb
+(unsigned int u, unsigned int g, struct cdb *c,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the *<em>c</em> CDB database for an authorization for uid <em>u</em>
+and gid <em>g</em>. If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_uidgid_fs
+(unsigned int u, unsigned int g, char const *dir,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the <em>dir</em> base directory for an authorization for uid <em>u</em>
+and gid <em>g</em>. If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_reversedns_cdb
+(char const *name, struct cdb *c,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the *<em>c</em> CDB database for an authorization for the
+<em>name</em> FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_reversedns_fs
+(char const *name, char const *dir,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the <em>dir</em> base directory for an authorization for the
+<em>name</em> FQDN. If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip4_cdb
+(char const *ip4, struct cdb *c,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the *<em>c</em> CDB database for an authorization for the
+<em>ip4</em> IPv4 address (4 network byte order characters).
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip4_fs
+(char const *ip4, char const *dir,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the <em>dir</em> base directory for an authorization for the
+<em>ip4</em> IPv4 address (4 network byte order characters).
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip6_cdb
+(char const *ip6, struct cdb *c,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the *<em>c</em> CDB database for an authorization for the
+<em>ip6</em> IPv6 address (16 network byte order characters).
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip6_fs
+(char const *ip6, char const *dir,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the <em>dir</em> base directory for an authorization for the
+<em>ip6</em> IPv6 address (16 network byte order characters).
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip46_cdb
+(ip46_t *ip, struct cdb *c,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the *<em>c</em> CDB database for an authorization for the
+<em>ip</em> IP address.
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+<p>
+<code> s6net_accessrules_result_t s6net_accessrules_ip46_fs
+(ip46_t const *ip, char const *dir,
+s6net_accessrules_params_t *params) </code> <br />
+Checks the <em>dir</em> base directory for an authorization for the
+<em>ip</em> IP address.
+If the result is S6NET_ACCESSRULES_ALLOW, additional
+information may be stored into <em>params</em>.
+</p>
+
+</body>
+</html>
diff --git a/doc/libs6net/ident.html b/doc/libs6net/ident.html
new file mode 100644
index 0000000..74a9217
--- /dev/null
+++ b/doc/libs6net/ident.html
@@ -0,0 +1,124 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the ident library interface</title>
+    <meta name="Description" content="s6-networking: the ident library interface" />
+    <meta name="Keywords" content="s6-networking net ident library libs6net ident RFC 1413" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="index.html">libs6net</a><br />
+<a href="../">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>ident</tt> library interface </h1>
+
+<p>
+ The following functions and structures are declared in the <tt>s6-networking/ident.h</tt> header,
+and implemented in the <tt>libs6net.a</tt> or <tt>libs6net.so</tt> library.
+</p>
+
+<h2> General information </h2>
+
+<p>
+ <tt>ident</tt> provides a C IDENT client, following RFC 1413.
+</p>
+
+<p>
+ Please note that this protocol is of historical interest exclusively;
+this client, as well as the <a href="../minidentd.html">minidentd</a>
+server, is only provided for convenience and interoperability with
+legacy systems. The IDENT protocol absolutely cannot be relied on for
+any kind of authentication or secure operation.
+</p>
+
+<h2> Functions </h2>
+
+<p>
+ Check the <tt>s6-networking/ident.h</tt> header for the exact function prototypes.
+</p>
+
+<h3> Main interface </h3>
+
+<p>
+<code> int s6net_ident_client (char *s, unsigned int max, ip46_t const *remoteip, uint16 remoteport, ip46_t const *localip, uint16 localport,
+struct taia const *deadline, struct taia *stamp) </code>
+</p>
+
+<p>
+Makes an IDENT request to a server listening on IP <em>remoteip</em> port 113
+about the connection from IP <em>remoteip</em> port <em>remoteport</em> to
+IP <em>localip</em> port <em>localport</em>. Writes the answer into
+preallocated string <em>s</em> of max length <em>max</em>, and returns the
+number of bytes in the answer.
+</p>
+
+<ul>
+ <li> An <a href="http://skarnet.org/software/skalibs/libstddjb/ip46.html">ip46_t</a>
+is a structure holding either an IPv4 address or an IPv6 address. </li>
+ <li> If an error occurs, the function returns -1 and sets errno to a
+suitable value. If no answer can be gotten from the server, the function
+returns 0 and sets errno to a suitable value. </li>
+ <li> If <em>max</em> is too small for <em>s</em> to hold the answer, the
+function returns -1 ENAMETOOLONG.
+This can be avoided by using S6NET_IDENT_REPLY_SIZE
+as <em>max</em>. </li>
+ <li> Negative answers are mapped to errno in the following way:
+  <ul>
+   <li> INVALID-PORT is reported as EINVAL </li>
+   <li> NO-USER is reported as ESRCH </li>
+   <li> HIDDEN-USER is reported as EPERM </li>
+   <li> UNKNOWN-ERROR is reported as EIO </li>
+   <li> extended error codes are reported as EEXIST </li>
+  </ul> </li>
+ <li> *<em>deadline</em> and *<em>stamp</em> are
+<a href="http://skarnet.org/software/skalibs/libstddjb/tai.h">absolute dates</a>:
+*<em>stamp</em> must be an accurate enough approximation of the current time, and
+is automatically updated when the function returns. If no answer has been gotten
+from the server by *<em>deadline</em>, then the call is aborted and returns
+-1 ETIMEDOUT. </li>
+</ul>
+
+<p>
+<code> char const *s6net_ident_error_str (int e) </code>
+</p>
+
+<p>
+ Maps an error code representing a negative answer (i.e. errno when
+<tt>s6net_ident_client</tt> returned 0) to a suitable string.
+</p>
+
+<h3> Low-level functions </h3>
+
+<p>
+<code> int s6net_ident_reply_get (char *s, ip46_t const *ra, uint16 rp, ip46_t const *la, uint16 lp,
+struct taia const *deadline, struct taia *stamp) </code>
+</p>
+
+<p>
+The network part of <tt>s6net_ident_client</tt>. Connects to *<em>ra</em>:113
+and asks the server about (*<em>ra</em>:<em>rp</em>,&nbsp;*<em>la</em>:<em>lp</em>),
+aborting if *<em>deadline</em> goes by. Writes the server answer into <em>s</em>;
+at least S6NET_IDENT_REPLY_SIZE bytes must be preallocated in <em>s</em>.
+Returns -1 if an error occurs, or the number of bytes written into <em>s</em>.
+</p>
+
+<p>
+<code> int s6net_ident_reply_parse (char const *s, uint16 rp, uint16 lp) </code>
+</p>
+
+<p>
+The local part of <tt>s6net_ident_client</tt>. Parses the server answer in
+<em>s</em> for the connection from port <em>rp</em> to port <em>lp</em>.
+Returns -1 EPROTO if the answer does not make sense, 0 if the answer is
+negative, or a positive number if the answer is positive. This number is
+an index where the ID can be found in <em>s</em>.
+</p>
+
+</body>
+</html>
diff --git a/doc/libs6net/index.html b/doc/libs6net/index.html
new file mode 100644
index 0000000..7a6a75b
--- /dev/null
+++ b/doc/libs6net/index.html
@@ -0,0 +1,63 @@
+<html>
+  <head>
+    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
+    <meta http-equiv="Content-Language" content="en" />
+    <title>s6-networking: the s6net library interface</title>
+    <meta name="Description" content="s6-networking: the s6net library interface" />
+    <meta name="Keywords" content="s6-networking net s6net library libs6net" />
+    <!-- <link rel="stylesheet" type="text/css" href="http://skarnet.org/default.css" /> -->
+  </head>
+<body>
+
+<p>
+<a href="../">s6-networking</a><br />
+<a href="http://skarnet.org/software/">Software</a><br />
+<a href="http://skarnet.org/">skarnet.org</a>
+</p>
+
+<h1> The <tt>s6net</tt> library interface </h1>
+
+<h2> General information </h2>
+
+<p>
+ <tt>libs6net</tt> is a collection of networking-related utility
+C interfaces, used in the s6-networking executables.
+</p>
+
+<h2> Compiling </h2>
+
+<ul>
+ <li> Make sure the s6-networking headers, as well as the skalibs headers,
+are visible in your header search path. </li>
+ <li> Use <tt>#include &lt;s6-networking/s6net.h&gt;</tt> </li>
+</ul>
+
+<h2> Linking </h2>
+
+<ul>
+ <li> Make sure the s6-networking libraries, as well as the skalibs
+libraries, are visible in your library search path. </li>
+ <li> Link against <tt>-ls6net</tt>, <tt>-lskarnet</tt>, </li>
+<tt>`cat $SYSDEPS/socket.lib`</tt> and
+<tt>`cat $SYSDEPS/tainnow.lib`</tt>, $SYSDEPS being your skalibs
+sysdeps directory. </li>
+</ul>
+
+<h2> Programming </h2>
+
+<p>
+ The <tt>s6-networking/s6net.h</tt> header is actually a
+concatenation of other headers:
+the libs6net is separated into several modules, each of them with its
+own header.
+</p>
+
+<ul>
+ <li> The <a href="accessrules.html">s6-networking/accessrules.h</a> header
+provides function to check credentials against configuration files. </li>
+ <li> The <a href="ident.html">s6-networking/ident.h</a> header provides
+a small IDENT client (RFC 1413). </li>
+</ul>
+
+</body>
+</html>
author	Laurent Bercot <ska-skaware@skarnet.org>	2014-12-15 23:08:59 +0000
committer	Laurent Bercot <ska-skaware@skarnet.org>	2014-12-15 23:08:59 +0000
commit	e0fc82203d677a6f1e808e9a1a46176c109d89be (patch)
tree	e9609209b755e3f7a8480aea86601ffe9d4ca540 /doc/libs6net
download	s6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz