SKEYLOOKUP(3) | Library Functions Manual | SKEYLOOKUP(3)

# NAME

`atob8`, `backspace`, `btoa8`, `btoe`, `etob`, `f`, `htoi`, `keycrunch`, `put8`, `readpass`, `readskey`, `rip`, `sevenbit`, `skey_authenticate`, `skey_get_algorithm`, `skey_haskey`, `skey_keyinfo`, `skey_passcheck`, `skey_set_algorithm`, `skey_unlock`, `skeychallenge`, `skeychallenge2`, `skeygetnext`, `skeylookup`, `skeyverify`, `skipspace` — S/Key library functions

# SYNOPSIS

library “libskey”
`#include <skey.h>`

int
`atob8`(char *out, char *in);

void
`backspace`(char *buf);

int
`btoa8`(char *out, char *in);

char *
`btoe`(char *engout, char *c);

int
`etob`(char *out, char *e);

void
`f`(char *x);

int
`htoi`(int h);

int
`keycrunch`(char *result, char *seed, char *passwd);

char *
`put8`(char *out, char *s);

char *
`readpass`(char *buf, int n);

char *
`readskey`(char *buf, int n);

void
`rip`(char *buf);

void
`sevenbit`(char *s);

int
`skey_authenticate`(char *user);

const char *
`skey_get_algorithm`(void);

int
`skey_haskey`(char *user);

char *
`skey_keyinfo`(char *user);

int
`skey_passcheck`(char *user, char *passwd);

char *
`skey_set_algorithm`(char *new);

int
`skey_unlock`(struct skey *rec);

int
`skeychallenge`(struct skey *rec, char *user, char *buf);

int
`skeychallenge2`(int fd, struct skey *rec, char *user, char *buf);

int
`skeygetnext`(struct skey *rec);

int
`skeylookup`(struct skey *rec, char *user);

int
`skeyverify`(struct skey *rec, char *response);

char *
`skipspace`(char *);

# DESCRIPTION

These functions implement the S/Key one time password authentication mechanism.

The `atob8`() function converts the 16-byte hex string in to an 8-byte binary array stored in out. The `atob8`() function returns 0 on success and -1 if an invalid hex character is encountered.

The `backspace`() function removes backspaced over characters from buf. Note that `backspace`() assumes the actual backspace character is 0x8 (^H).

The `btoa8`() function converts the 8-byte binary array in to a 16-byte string of hex digits stored in out; the caller must supply enough space (17 bytes including the final NUL). The `btoa8`() function returns 0 on success and -1 if an error occurred.

The `btoe`() function encodes the 8 bytes in c into a string of 6 English words, stored in engout. The caller must supply enough space (30 bytes including the final NUL) to store the words. The `btoe`() function returns engout.

The `etob`() function converts the 6 English words in e into an 8-byte binary representation. The `etob`() function returns 1 if the words are all in the database and parity is correct, 0 if a word is not in the database, -1 if the number of words is incorrect, or -2 if there is a parity error.

The `f`() function is a one-way hash that overwrites the 8-byte input buffer x with the hashed result.

The `htoi`() function converts a single hex digit h to an integer. The `htoi`() function returns the converted integer on success or -1 if h not a valid hex digit.

The `keycrunch`() function concatenates the seed and passwd, runs them through a hash function and collapses the result to 64 bits. The `keycrunch`() function returns 0 on success or -1 if there is a memory allocation failure.

The `put8`() function converts the 8 bytes stored in s into a series of 4 16-bit hex digit stored in out. There must be at least 20 bytes (including the NUL) in the output buffer, out. The `put8`() function returns out.

The `readpass`() function reads up to n characters from standard input with echo turned off, converting the resulting string to 7 bits, storing the result in buf. The `readpass`() function returns buf.

The `readskey`() function reads up to n characters from standard input with echo turned on, converting the resulting string to 7 bits, storing the result in buf. The `readskey`() function returns buf.

The `rip`() function strips trailing linefeeds and carriage returns from buf.

The `sevenbit`() function strips the high bit from each character in s, converting the characters to seven bit ASCII.

The `skey_authenticate`() function presents the user with an S/Key challenge and authenticates the response. The `skey_authenticate`() function returns 0 if authentication is successful or -1 if not.

The `skey_get_algorithm`() function returns a string corresponding to the hash algorithm for the current user. The default algorithm is “md5”.

The `skey_haskey`() function returns 0 if the user exists in the S/Key database, 1 if the user does not exist, or -1 if there was an error reading the database.

The `skey_keyinfo`() function returns a string containing the current sequence number and seed for user. The returned string points to internal static storage that will be overwritten by subsequent calls to `skey_keyinfo`().

The `skey_passcheck`() function checks a user and passwd pair against the S/Key database. It returns 0 on successful authentication or -1 on failure.

The `skey_set_algorithm`() function sets the user's hash algorithm based on the string new. The `skey_set_algorithm`() function returns the specified algorithm if it is supported, or the null pointer if the hash algorithm is not supported.

The `skey_unlock`() function unlocks the record in the S/Key database specified by rec. The `skey_unlock`() function returns 0 on success or -1 on failure. Either way, the S/Key database is not closed nor is the database file pointer affected.

The `skeychallenge`() function stores the (potentially fake) S/Key challenge for user in buf, which is at least SKEY_MAX_CHALLENGE bytes long. It also fills in the skey struct rec and locks the user's record in the S/Key database. The `skeychallenge`() function returns 0 on success or -1 on failure. On success the S/Key database remains open and the read/write file pointer is set to the beginning of the record.

The `skeychallenge2`() function is identical to `skeychallenge`() except that instead of opening the user's entry in the S/Key database, the open file referenced by fd is used instead. When fd is -1, the behavior is equivalent to `skeychallenge`().

The `skeygetnext`() function stores the next record in the S/Key database in rec and locks that record in the S/Key database. The `skeygetnext`() function returns 0 on success, 1 if there are no more entries, or -1 if there was an error accessing the S/Key database. The S/Key database remains open after a call to `skeygetnext`(). If no error was encountered accessing the S/Key database, the read/write file pointer is set to the beginning of the record or at EOF if there are no more records.
Because it exposes other users' S/Key records, only the superuser may use `skeygetnext`().

The `skeylookup`() function looks up the specified user in the S/Key database then fills in the skey struct rec and locks the user's record in the database. The `skeylookup`() function returns 0 on success, 1 if user was not found, or -1 if there was an error accessing the S/Key database. If no error was encountered accessing the S/Key database, the read/write file pointer is set to the beginning of the record.

The `skeyverify`() function verifies the user's response based on the S/Key record rec. It returns 0 on success (updating the database), 1 on failure, or -1 if there was an error accessing the database. The database is always closed by a call to `skeyverify`().

# SEE ALSO

skey(1), skeyinit(1)

# STANDARDS

There is no standard API for S/Key. The de facto standard is the free S/Key distribution released by Bellcore.

The following functions are extensions and do not appear in the original Bellcore S/Key distribution: `readskey`(), `skey_authenticate`(), `skey_get_algorithm`(), `skey_haskey`(), `skey_keyinfo`(), `skey_passcheck`(), `skey_set_algorithm`(), `skey_unlock`().

S/Key is a Trademark of Bellcore.

June 6, 2025 | Debian