[src/trunk]: src/lib/libskey Add and install skey(3).

[gmcgarry <gmcgarry%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/0b18a1e2242b
branches:  trunk
changeset: 517286:0b18a1e2242b
user:      gmcgarry <gmcgarry%NetBSD.org@localhost>
date:      Sat Nov 10 06:11:10 2001 +0000

description:
Add and install skey(3).

diffstat:

 lib/libskey/Makefile |   17 +++-
 lib/libskey/skey.3   |  259 +++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 275 insertions(+), 1 deletions(-)

diffs (291 lines):

diff -r 623377ff83e6 -r 0b18a1e2242b lib/libskey/Makefile
--- a/lib/libskey/Makefile      Sat Nov 10 05:16:43 2001 +0000
+++ b/lib/libskey/Makefile      Sat Nov 10 06:11:10 2001 +0000
@@ -1,8 +1,23 @@
-#      $NetBSD: Makefile,v 1.4 1997/10/23 03:23:03 lukem Exp $
+#      $NetBSD: Makefile,v 1.5 2001/11/10 06:11:10 gmcgarry Exp $
 
 LIB=   skey
 SRCS=  skeylogin.c skeysubr.c put.c
 INCS=  skey.h
 INCSDIR=/usr/include
 
+MAN=   skey.3
+
+MLINKS=        skey.3 skeychallenge.3 \
+       skey.3 skeylookup.3 \
+       skey.3 skeygetnext.3 \
+       skey.3 skeyverify.3 \
+       skey.3 skeyzero.3 \
+       skey.3 getskeyprompt.3 \
+       skey.3 skey_set_algorithm.3 \
+       skey.3 skey_get_algorithm.3 \
+       skey.3 skey_haskey.3 \
+       skey.3 skey_keyinfo.3 \
+       skey.3 skey_passcheck.3 \
+       skey.3 skey_authenticate.3
+
 .include <bsd.lib.mk>
diff -r 623377ff83e6 -r 0b18a1e2242b lib/libskey/skey.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libskey/skey.3        Sat Nov 10 06:11:10 2001 +0000
@@ -0,0 +1,259 @@
+.\"     $NetBSD: skey.3,v 1.1 2001/11/10 06:11:10 gmcgarry 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 (eg if name in 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 (eg if name in 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-bte 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
+in put (ie > 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
+the static skey library
+.It Pa /usr/lib/libskey.so
+the dynamic skey library
+.It Pa /usr/lib/libskey_p.a
+the static skey library compiled for profiling
+.El
+.Sh SEE ALSO
+.Xr skey 1 ,
+.Xr skeyinfo 1 ,
+.Xr skeyaudit 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.