s6-networking: the ident library interface
Keywords: s6-networking net ident library libs6net ident RFC 1413

libs6net
s6-networking
Software
skarnet.org

# The `ident` library interface

The following functions and structures are declared in the `s6-networking/ident.h` header, and implemented in the `libs6net.a` or `libs6net.so` library.

## General information

`ident` provides a C IDENT client, following RFC 1413.

Please note that this protocol is of historical interest exclusively; this client 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.

## Functions

Check the `s6-networking/ident.h` header for the exact function prototypes.

### Main interface

`ssize_t s6net_ident_client (char *s, size_t max, ip46_t const *remoteip, uint16_t remoteport, ip46_t const *localip, uint16_t localport, tain_t const *deadline, tain_t *stamp)`

Makes an IDENT request to a server listening on IP remoteip port 113 about the connection from IP remoteip port remoteport to IP localip port localport. Writes the answer into preallocated string s of max length max, and returns the number of bytes in the answer.

- An ip46_t is a structure holding either an IPv4 address or an IPv6 address.
- 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.
- If max is too small for s to hold the answer, the function returns -1 ENAMETOOLONG. This can be avoided by using S6NET_IDENT_REPLY_SIZE as max.
- Negative answers are mapped to errno in the following way:
  - INVALID-PORT is reported as EINVAL
  - NO-USER is reported as ESRCH
  - HIDDEN-USER is reported as EPERM
  - UNKNOWN-ERROR is reported as EIO
  - extended error codes are reported as EEXIST
- *deadline and *stamp are absolute dates: *stamp 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 *deadline, then the call is aborted and returns -1 ETIMEDOUT.

`char const *s6net_ident_error_str (int e)`

Maps an error code representing a negative answer (i.e. errno when `s6net_ident_client` returned 0) to a suitable string.

### Low-level functions

`ssize_t s6net_ident_reply_get (char *s, ip46_t const *ra, uint16_t rp, ip46_t const *la, uint16_t lp, tain_t const *deadline, tain_t *stamp)`

The network part of `s6net_ident_client`. Connects to *ra:113 and asks the server about (*ra:rp, *la:lp), aborting if *deadline goes by. Writes the server answer into s; at least S6NET_IDENT_REPLY_SIZE bytes must be preallocated in s. Returns -1 if an error occurs, or the number of bytes written into s.

`ssize_t s6net_ident_reply_parse (char const *s, uint16_t rp, uint16_t lp)`

The local part of `s6net_ident_client`. Parses the server answer in s for the connection from port rp to port lp. 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 s.