sident(3)

NAME

ident_query, ident_lookup, ident_id, ident_free,
ident_set_authtype, ident_set_authflag, ident_get_authflag,
ident_query_error - Query remote S/Ident responder

SYNOPSIS

#include <sident.h>
IDENT *ident_query(struct in_addr *laddr,  struct  in_addr
*raddr, int resp_port, int req_port, int timeout)
IDENT *ident_lookup(int fd, inttimeout)
char *ident_id(int fd, int timeout)
void ident_free(IDENT *id)
int      ident_set_authtype(char      *authtype,      void
*auth_init_data)
int ident_set_authflag(char *flag, char *value)
int ident_get_authflag(char *flag, char **value)
int  ident_query_error(char  *flag,  char  *value,   IDENT
*ident_ptr)

DESCRIPTION

The S/Ident protocol is used to authenticate a user who is
connecting to a remote network service using a protocol (or soft
ware) which does not support authentication. The user connects
to a remote server, that server opens a connection back to the
client (a callback), and the callback is answered by a daemon on
the client machine that returns the user's authentication out of
band. In the S/Ident standard, the remote server that is trying
to authenticate the user is called the requester, and the daemon
on the client system that returns the authentication information
is called the responder.
The S/Ident library, libsident, provides an API for
S/Ident requesters to make a query back to the connecting host
for authentication information associated with a particular con
nection. There are three different high-level calls, depending
on how much information is needed and whether the caller has an
open network file descriptor.
ident_query is the most "raw" of the three calls. It re
quires the local address of the requester system, the remote ad
dress, and the ports on the responder and requester systems and
returns an IDENT struct (described below). If a network connec
tion cannot be made to the responder, it returns NULL. This may
indicate a network problem, or may indicate that the remote host
is not running an S/Ident responder. If the network connection
is successful but the authentication fails, there will be a non
zero status in the result_code field of the IDENT struct.
ident_lookup does the same but instead takes the file de
scriptor of a connected network socket and gets the IP addresses
and ports from that. Its return value is the same as
ident_query.
ident_id takes the same arguments as ident_lookup but re
turns only the identifier component of the IDENT struct (see be
low) on success. The return value is newly allocated memory that
should be freed with a regular call to free(3). ident_id returns
NULL on any error, network or otherwise, and only returns
identifier on successful authentication.
All three functions take a timeout argument, which speci
fies the longest permissable time to block for an answer in sec
onds. A value of 0 says to wait indefinitely (in practice, gen
erally until the underlying network connection times out).
ident_free should be used to free a returned IDENT struct,
including all data contained in it.
ident_set_authtype sets the type of authentication to re
quest. There are currently three supported values: "KER
BEROS_V4", "GSSAPI", and "TRIVIAL". (The "TRIVIAL" authentica
tion type behaves the same as the standard Ident protocol and
doesn't do any strong authentication.) The second argument to
ident_set_authtype is a pointer to whatever initialization data
is required for that authentication type. Currently, the only
authentication type that takes additional data is "KERBEROS_V4",
which takes a pointer to the location of the srvtab file to use.
The srvtab should contain a key for ident.hostname where hostname
is the DNS name of the network interface that will be making the
request.
(There is no direct way to specify the keytab to use for
the GSS-API method because GSS-API doesn't have a way to specify
it. You can, however, set the KRB5_KTNAME environment variable
to point to the appropriate keytab.)
ident_set_authflag sets an optional flag in the initial
authentication request. Currently, the only supported flag is
"USER-INTERACTION", which can be set to "YES" or "NO". If set to
"YES", the requester asks that the user be prompted to log in if
possible and if they don't have current credentials. If set to
"NO", the requester asks that the user not be prompted and that
authentication fail if they don't have current credentials.
ident_set_authtype must be called before this call can be used.
ident_get_authflag queries the current value of a flag. A
pointer to the value string is returned in the value argument.
ident_set_authtype must be called before this call can be used.
ident_query_error interrogates an error return (in the
form of an IDENT struct) for a given flag and corresponding val
ue. If the flag and value are present, it returns
IDENT_AUTH_OKAY; otherwise, it returns IDENT_AUTH_FAIL. The two
defined flags are "CAPABILITIES" and "AUTH-MECH".
The only allowable value for "CAPABILITIES" is "USER-IN
TERACTION". It will be returned if authentication failed because
the user didn't have current credentials but the responder is ca
pable of prompting for them if the "USER-INTERACTION" flag is
set. The requester may want to set that flag with
ident_set_authflag and then retry the query.
The "AUTH-MECH" flag is used to query the responder for
its supported SASL mechanisms. Because of the nature of the
S/Ident protocol, it doesn't do the normal SASL negotation first.
Instead, the requester starts by just using some particular SASL
protocol, which the responder either supports or doesn't. If it
doesn't support it, the returned error lists the mechanisms that
are supported. This information can be queried using
ident_query_error; the flag value should be the name of a SASL
mechanism, and the return code will indicate whether the respon
der said it supported that mechanism. Note that GSS-API mecha
nisms are separately listed as type/subtype. The only currently
supported GSS-API mechanism is "GSSAPI/KERBEROS_v5".
The IDENT struct has the following definition:: typedef struct {
int resp_port; /* Responder port. */
int req_port; /* Requester port (i.e. us).

*/
char *identifier; /* Identification string. */
char *opsys; /* Operating system. */
char *charset; /* Character set. */
int result_code; /* Result code from internal

routines. */
time_t expires; /* Expiration of authenticat

ing ticket. */
char *principal; /* Principal in local realm.

*/; } IDENT;
identifier contains the authenticated identity (princi
pal@realm for Kerberos v4 or GSS-API Kerberos v5 authentication),
a colon, and identifier returned by the remote system (generally
the local Unix user name or UID). In the event of an error,
identifier will instead contain a string representation of the
error. principal will contain only the principal portion of the
Kerberos identity if its real matches the local realm. Other
wise, and on any error, it will be NULL.
The opsys and charset fields contain that information if
it's specified in the S/Ident response, but are rarely useful.
They will be set to NULL if that information was not specified.
result_code contains the error status of the call. See
ERRORS for detailed information. If there is no error, it will
be set to 0 (IDENT_AUTH_OKAY).
expires contains the time (in seconds since epoch) when
the underlying authentication credentials of the user will ex
pire.

ERRORS

The following codes are defined by the S/Ident library and
are used for the result_code field of the IDENT struct and for
other error returns. IDENT_AUTH_OKAY and IDENT_AUTH_FAIL are
used as convenient boolean return codes for some functions.
IDENT_AUTH_OKAY: The operation was successful.
IDENT_AUTH_FAIL: Verification of authentication failed. (Or, when used; outside of the IDENT struct, indicates that some error occurred.)
IDENT_AUTH_NOT_SUPPORTED: The authentication mechanism used by the requester is; not supported for authentication of the owner of the indicated; connection. The requester may wish to use ident_query_error with; the "AUTH-MECH" flag to find another acceptable, supported SASL; mechanism.
IDENT_USER_CANT_AUTH: The authentication mechanism was supported, but no au; thentication information is available for that user. Either they; don't have valid credentials, they've chosen not to authenticate,; or some similar failure occurred.
IDENT_INVALID_RESP_INFO: The response from the responder was syntactically in; valid according to the S/Ident protocol.
IDENT_INVALID_REQ_INFO: The query from the responder was syntactically invalid; according ot the S/Ident protocol.
IDENT_NO_USER: The connection specified is not currently in use or is; not currently owned by an identifiable entity.
IDENT_UNKNOWN_ERROR: Some error occurred which is not covered by the other; error codes. Optionally, this code MAY be returned in lieu of; any other specific error code if, for example, the server desires; to hide information implied by the return of that error code, or; for any other reason.; This error code is also used if the remote system; closed the connection without returning any response.
IDENT_INVALID_PORT: Either the local or foreign port was improperly speci; fied. This should be returned if either or both of the port ids; were out of range (TCP port numbers are from 1-65535), negative; integers, reals or in any fashion not recognized as a non-nega; tive integer.
IDENT_HIDDEN_USER: The server was able to identify the user of this port,; but the information was not returned at the request of the user.

EXAMPLES

The following code fragment shows how to check for an au
thenticated connection (assuming that the network connection is
on standard input, as with a server started from inetd):: IDENT *ident;; ident_set_authtype("GSSAPI", NULL);
ident = ident_lookup(fileno(stdin), 30);
if (ident != NULL) {
if (ident->result_code == IDENT_AUTH_OKAY)
printf("User authenticated as %s0,

ident->identifier);

else

printf("Authentication failed: %s0,

ident->identifier);

} else

printf("Unable to contact S/Ident responder0);

ident_free(ident);

BUGS

The S/Ident protocol has some significant flaws in the
presence of NAT, firewalls, and the like. See the sidentd(8)
manual page for more details.
For ident_lookup and ident_id, the blocking time in ex
treme cases may be as much as three times the value given in the
timeout parameter.
The described interface doesn't allow for non-blocking
queries, and the low-level API that would allow for them is not
described here and isn't particularly attractive. Ideally, the
above API should be extended slightly to allow for non-blocking
queries.
This API isn't even remotely thread-safe, as is immediate
ly apparent.

WARNING

The S/Ident protocol implemented by this package is inher
ently vulnerable to an active man-in-the-middle attack. If an
attacker can interpose themselves into a network connection ini
tiated by a victim and both impersonate that victim and selec
tively control which of their packets reach a server using
S/Ident, the attacker can make use of the victim's authentication
credentials. The attacker cannot initiate the session, only hi
jack an existing authenticated session.
Because of this, you should very carefully analyze the se
curity requirements of any service for which you're considering
deploying S/Ident authentication. Due to the requirements of the
attack, S/Ident may still be appropriate for very light authenti
cation or in secure network environments, but should not be used
for general authentication on untrusted networks.

AUTHORS

Originally written by Booker Bense <bbense@stanford.edu>
based on the S/Ident protocol proposed by Robert Morgan <mor
gan@stanford.edu>. GSS-API support added by Russ Allbery
<rra@stanford.edu>, who currently maintains this package.
The code is based on the pidentd/libident code from Peter
Eriksson <pen@lysator.liu.se> and Paer Emanuelsson
<pell@lysator.liu.se>. The SASL-like kerberos exchange is based
on code from CMU's imapd-1.4 release.

COPYRIGHT AND LICENSE

2004 Board of Trustees, Leland Stanford Jr. University.
Portions based on source from Peter Eriksson
<pen@lysator.liu.se> contained in the libident library, released
into the public domain.
Mellon University.
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the following
conditions are met:
1. Redistributions of source code must retain the above
copyright notice, this list of conditions and the following dis
claimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following dis
claimer in the documentation and/or other materials provided with
the distribution.
3. The name "Carnegie Mellon University" must not be used
to endorse or promote products derived from this software without
prior written permission. For permission or any legal details,
please contact: Office of Technology Transfer
Carnegie Mellon University
5000 Forbes Avenue
Pittsburgh, PA 15213-3890
(412) 268-4387, fax: (412) 268-7395
tech-transfer@andrew.cmu.edu; 4. Redistributions of any form whatsoever must retain the
following acknowledgment:: "This product includes software developed by Com
puting Services at Carnegie Mellon University
(http://www.cmu.edu/computing/)."
STANFORD UNIVERSITY AND CARNEGIE MELLON UNIVERSITY DIS
CLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT
SHALL STANFORD UNIVERSITY OR CARNEGIE MELLON UNIVERSITY BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER
IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
THIS SOFTWARE.
3.6 2005-10-04

docs.sk

comprehensive documentation repository

See also

sident(3)

NAME

SYNOPSIS

DESCRIPTION

ERRORS

EXAMPLES

BUGS

WARNING

SEE ALSO

AUTHORS

COPYRIGHT AND LICENSE