260 lines
7.9 KiB
Groff
260 lines
7.9 KiB
Groff
.\" $NetBSD: skey.3,v 1.2 2001/11/10 08:05:51 wiz 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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
|
|
.Fd #include <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"
|
|
Check 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 repsonse 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. > 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.
|