SKEY(3)

NAME
skeylookup, skeyverify, skeychallenge, skeyinfo, skeyaccess, skey_getpass, skey_crypt - library routines for S/Key password control table access

LIBRARY
libskey

SYNOPSIS
#include <stdio.h>
#include <skey.h>
int
skeylookup(struct skey *mp, const char *name);
int
skeyverify(struct skey *mp, char *response);
int
skeychallenge(struct skey *mp, const char *name, char *challenge);
int
skeyinfo(struct skey *mp, const char *name, char *ss);
int
skeyaccess(char *user, const char *port, const char *host, const char *addr);
char *
skey_getpass(const char *prompt, struct passwd *pwd, int pwok);
const char *
skey_crypt(char *pp, char *salt, struct passwd *pwd, int pwok);

DESCRIPTION
These routes support the S/Key one time password system used for accessing computer systems. See skey(1) for more information about the S/Key system itself.

skeylookup() finds an entry in the one-time password database. On success (an entry is found corresponding to the given name), they skey structure passed by the caller is filled and 0 is returned, with the file read/write pointer positioned at the beginning of the record found. If no entry is found corresponding to the given name, the file read/write pointer is positioned at end of file and the routine returns 1. If the database cannot be opened or an access error occurs, skeylookup() returns -1.

The skeyinfo() function looks up skey info for user 'name'. If successful, the caller's skey structure is filled and skeyinfo() returns 0. If an optional challenge string buffer is given, it is updated. If unsuccessful (e.g. if the name is unknown, or the database cannot be accessed) -1 is returned.

skeychallenge() returns an skey challenge string for 'name'. If successful, the caller's skey structure is filled, and the function returns 0, with the file read/write pointer left at the start of the record. If unsuccessful (ie. the name was not found), the function returns -1 and the database is closed.

skeyverify() verifies a response to an s/key challenge. If this function returns 0, the verify was successful and the database was updated. If 1 is returned, the verify failed and the database remains unchanged. If -1 is returned, some sort of error occurred with the database, and the database is left unchanged. The s/key database is always closed by this call.

The skey_getpass() function may be used to read regular or s/key passwords. The prompt to use is passed to the function, along with the full (secure) struct passwd for the user to be verified. skey_getpass() uses the standard library getpass on the first attempt at retrieving the user's password, and if that is blank, turns echo back on and retrieves the S/Key password. In either case, the entered string is returned back to the caller.

The skey_crypt() is a wrapper function for the standard library crypt(3), which returns the encrypted UNIX password if either the given s/key or regular passwords are ok. skey_crypt() first attempts verification of the given password via the skey method, and will return the encrypted password from the passwd structure if it can be verified, as though the user had actually entered the correct UNIX password. If s/key password verification does not work, then the password is encrypted in the usual way and the result passed back to the caller. If the passwd structure pointer is NULL, skey_crypt() returns a non-NULL string which could not possibly be a valid UNIX password (namely, a string containing ":").

The skeyaccess() function determines whether traditional UNIX (non-S/Key) passwords are permitted for any combination of user name, group member, terminal port, host name, and network. If UNIX passwords are allowed, skeyaccess() returns a non-zero value. If UNIX passwords are not allowed, it returns 0. See skey.access(5) for more information on the layout and structure of the skey.access configuration file which this function uses.

RETURN VALUES
See above.

SEE ALSO
skey(1), skey.access(5)

BUGS
No advisory locking is done on the s/key database to guard against simultaneous access from multiple processes. This is not normally a problem when keys are added to or updated in the file, but may be problematic when keys are removed.

AUTHORS
Phil Karn, Neil M. Haller, John S. Walden, Scott Chasin