diff options
| 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/ident.html | |
| download | s6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz | |
Initial commit
Diffstat (limited to 'doc/libs6net/ident.html')
| -rw-r--r-- | doc/libs6net/ident.html | 124 |
1 files changed, 124 insertions, 0 deletions
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>, *<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> |