258 lines
7.4 KiB
Groff
258 lines
7.4 KiB
Groff
.\" $NetBSD: skey.3,v 1.9 2008/04/30 13:10:52 martin Exp $
|
|
.\"
|
|
.\" Copyright (c) 2001 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Gregory McGarry.
|
|
.\"
|
|
.\" 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 disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
|
|
.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
|
|
.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
|
|
.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
|
|
.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
|
|
.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
|
|
.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
|
|
.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
|
.\" POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd November 10, 2001
|
|
.Dt SKEY 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm skey ,
|
|
.Nm skeychallenge ,
|
|
.Nm skeylookup ,
|
|
.Nm skeygetnext ,
|
|
.Nm skeyverify ,
|
|
.Nm skeyzero ,
|
|
.Nm getskeyprompt ,
|
|
.Nm skey_set_algorithm ,
|
|
.Nm skey_get_algorithm ,
|
|
.Nm skey_haskey ,
|
|
.Nm skey_keyinfo ,
|
|
.Nm skey_passcheck ,
|
|
.Nm skey_authenticate
|
|
.Nd one-time password (OTP) library
|
|
.Sh LIBRARY
|
|
S/key One-Time Password Library (libskey, -lskey)
|
|
.Sh SYNOPSIS
|
|
.In skey.h
|
|
.Ft int
|
|
.Fn skeychallenge "struct skey *mp" "const char *name" "char *ss" \
|
|
"size_t sslen"
|
|
.Ft int
|
|
.Fn skeylookup "struct skey *mp" "const char *name"
|
|
.Ft int
|
|
.Fn skeygetnext "struct skey *mp"
|
|
.Ft int
|
|
.Fn skeyverify "struct skey *mp" "char *response"
|
|
.Ft int
|
|
.Fn skeyzero "struct skey *mp" "char *response"
|
|
.Ft int
|
|
.Fn getskeyprompt "struct skey *mp" "char *name" "char *prompt"
|
|
.Ft const char *
|
|
.Fn skey_set_algorithm "const char *new"
|
|
.Ft const char *
|
|
.Fn skey_get_algorithm "void"
|
|
.Ft int
|
|
.Fn skey_haskey "const char *username"
|
|
.Ft const char *
|
|
.Fn skey_keyinfo "const char *username"
|
|
.Ft int
|
|
.Fn skey_passcheck "const char *username" "char *passwd"
|
|
.Ft int
|
|
.Fn skey_authenticate "const char *username"
|
|
.Ft void
|
|
.Fn f "char *x"
|
|
.Ft int
|
|
.Fn keycrunch "char *result" "const char *seed" "const char *passwd"
|
|
.Ft void
|
|
.Fn rip "char *buf"
|
|
.Ft char *
|
|
.Fn readpass "char *buf " "int n"
|
|
.Ft char *
|
|
.Fn readskey "char *buf" "int n"
|
|
.Ft int
|
|
.Fn atob8 "char *out" "const char *in"
|
|
.Ft int
|
|
.Fn btoa8 "char *out" "const char *in"
|
|
.Ft int
|
|
.Fn htoi "int c"
|
|
.Ft const char *
|
|
.Fn skipspace "const char *cp"
|
|
.Ft void
|
|
.Fn backspace "char *buf"
|
|
.Ft void
|
|
.Fn sevenbit "char *buf"
|
|
.Ft char *
|
|
.Fn btoe "char *engout" "const char *c"
|
|
.Ft int
|
|
.Fn etob "char *out" "const char *e"
|
|
.Ft char *
|
|
.Fn put8 "char *out" "const char *s"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
library provides routines for accessing
|
|
.Nx Ns 's
|
|
one-time password (OTP) authentication system.
|
|
.Pp
|
|
Most S/Key operations take a pointer to a
|
|
.Em struct skey ,
|
|
which should be considered as an opaque identifier.
|
|
.Sh FUNCTIONS
|
|
The following high-level functions are available:
|
|
.Bl -tag -width compact
|
|
.It Fn skeychallenge "mp" "name" "ss" "sslen"
|
|
Return a S/Key challenge for user
|
|
.Fa name .
|
|
If successful, the caller's skey structure
|
|
.Fa mp
|
|
is filled and 0 is returned.
|
|
If unsuccessful (e.g. if name is unknown),
|
|
\-1 is returned.
|
|
.It Fn skeylookup "mp" "name"
|
|
Find an entry for user
|
|
.Fa name
|
|
in the one-time password database.
|
|
Returns 0 if the entry is found and 1 if the entry is not found.
|
|
If an error occurs accessing the database, \-1 is returned.
|
|
.It Fn skeygetnext "mp"
|
|
Get the next entry in the one-time password database.
|
|
Returns 0 on success and the entry is stored in
|
|
.Ar mp
|
|
and 1 if no more entries are available.
|
|
If an error occurs accessing the database, \-1 is returned.
|
|
.It Fn skeyverify "mp" "response"
|
|
Verify response
|
|
.Fa response
|
|
to a S/Key challenge.
|
|
Returns 0 if the verification is successful and 1 if the verification failed.
|
|
If an error occurs accessing the database, \-1 is returned.
|
|
.It Fn skeyzero "mp" "response"
|
|
Comment out user's entry in the S/Key database.
|
|
Returns 0 on success and the database is updated,
|
|
otherwise \-1 is returned and the database remains unchanged.
|
|
.It Fn getskeyprompt "mp" "name" "prompt"
|
|
Issue a S/Key challenge for user
|
|
.Ar name .
|
|
If successful, fill in the caller's skey structure
|
|
.Fa mp
|
|
and return 0.
|
|
If unsuccessful (e.g. if name is unknown) \-1 is returned.
|
|
.El
|
|
.Pp
|
|
The following lower-level functions are available:
|
|
.Bl -tag -width compact
|
|
.It Fn skey_set_algorithm "new"
|
|
Set hash algorithm type.
|
|
Valid values for
|
|
.Fa new
|
|
are "md4", "md5" and "sha1".
|
|
.It Fn skey_get_algorithm "void"
|
|
Get current hash type.
|
|
.It Fn skey_haskey "username"
|
|
Returns 0 if the user
|
|
.Fa username
|
|
exists and 1 if the user doesn't exist.
|
|
Returns \-1 on file error.
|
|
.It Fn skey_keyinfo "username"
|
|
Returns the current sequence number and seed for user
|
|
.Ar username .
|
|
.It Fn skey_passcheck "username" "passwd"
|
|
Checks to see if answer is the correct one to the current challenge.
|
|
.It Fn skey_authenticate "username"
|
|
Used when calling program will allow input of the user's response to
|
|
the challenge.
|
|
Returns zero on success or \-1 on failure.
|
|
.El
|
|
.Pp
|
|
The following miscellaneous functions are available:
|
|
.Bl -tag -width compact
|
|
.It Fn f "x"
|
|
One-way function to take 8 bytes pointed to by
|
|
.Fa x
|
|
and return 8 bytes in place.
|
|
.It Fn keycrunch "char *result" "const char *seed" "const char *passwd"
|
|
Crunch a key.
|
|
.It Fn rip "buf"
|
|
Strip trailing CR/LF characters from a line of text
|
|
.Fa buf .
|
|
.It Fn readpass "buf" "n"
|
|
Read in secret passwd (turns off echo).
|
|
.It Fn readskey "buf" "n"
|
|
Read in an s/key OTP (does not turn off echo).
|
|
.It Fn atob8 "out" "in"
|
|
Convert 8-byte hex-ascii string
|
|
.Fa in
|
|
to binary array
|
|
.Fa out .
|
|
Returns 0 on success, \-1 on error.
|
|
.It Fn btoa8 "out" "in"
|
|
Convert 8-byte binary array
|
|
.Fa in
|
|
to hex-ascii string
|
|
.Fa out .
|
|
Returns 0 on success, \-1 on error.
|
|
.It Fn htoi "int c"
|
|
Convert hex digit to binary integer.
|
|
.It Fn skipspace "cp"
|
|
Skip leading spaces from the string
|
|
.Fa cp .
|
|
.It Fn backspace "buf"
|
|
Remove backspaced over characters from the string
|
|
.Fa buf .
|
|
.It Fn sevenbit "buf"
|
|
Ensure line
|
|
.Fa buf
|
|
is all seven bits.
|
|
.It Fn btoe "engout" "c"
|
|
Encode 8 bytes in
|
|
.Ar c
|
|
as a string of English words.
|
|
Returns a pointer to a static buffer in
|
|
.Fa engout .
|
|
.It Fn etob "out" "e"
|
|
Convert English to binary.
|
|
Returns 0 if the word is not in the database, 1 if all good words and
|
|
parity is valid, \-1 if badly formed input (i.e. \*[Gt] 4 char word)
|
|
and -2 if words are valid but parity is wrong.
|
|
.It Fn put8 "out" "s"
|
|
Display 8 bytes
|
|
.Fa s
|
|
as a series of 16-bit hex digits.
|
|
.El
|
|
.Sh FILES
|
|
.Bl -tag -width /usr/lib/libskey_p.a -compact
|
|
.It Pa /usr/lib/libskey.a
|
|
static skey library
|
|
.It Pa /usr/lib/libskey.so
|
|
dynamic skey library
|
|
.It Pa /usr/lib/libskey_p.a
|
|
static skey library compiled for profiling
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr skey 1 ,
|
|
.Xr skeyaudit 1 ,
|
|
.Xr skeyinfo 1
|
|
.Sh BUGS
|
|
The
|
|
.Nm
|
|
library functions are not re-entrant or thread-safe.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
library defines many poorly named functions which pollute the name space.
|