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
#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
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.