summaryrefslogtreecommitdiff
path: root/doc/libs6net/ident.html
diff options
context:
space:
mode:
authorLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
committerLaurent Bercot <ska-skaware@skarnet.org>2014-12-15 23:08:59 +0000
commite0fc82203d677a6f1e808e9a1a46176c109d89be (patch)
treee9609209b755e3f7a8480aea86601ffe9d4ca540 /doc/libs6net/ident.html
downloads6-networking-e0fc82203d677a6f1e808e9a1a46176c109d89be.tar.xz
Initial commit
Diffstat (limited to 'doc/libs6net/ident.html')
-rw-r--r--doc/libs6net/ident.html124
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>,&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>