diff options
| -rw-r--r-- | lib/libskey/Makefile | 13 | ||||
| -rw-r--r-- | lib/libskey/skey.3 | 392 |
2 files changed, 403 insertions, 2 deletions
diff --git a/lib/libskey/Makefile b/lib/libskey/Makefile index 714b31da9c1..d86337fdf79 100644 --- a/lib/libskey/Makefile +++ b/lib/libskey/Makefile @@ -1,9 +1,18 @@ -# $OpenBSD: Makefile,v 1.5 2000/03/02 00:29:51 todd Exp $ +# $OpenBSD: Makefile,v 1.6 2001/06/23 21:34:40 millert Exp $ LIB= skey SRCS= skeylogin.c skeysubr.c put.c HDRS= skey.h -#CFLAGS+= -DSKEY_MDX_DEFAULT=4 +MAN+= skey.3 +MLINKS+=skey.3 atob8.3 skey.3 backspace.3 skey.3 btoa8.3 skey.3 btoe.3 \ + skey.3 etob.3 skey.3 f.3 skey.3 htoi.3 skey.3 keycrunch.3 \ + skey.3 put8.3 skey.3 readpass.3 skey.3 readskey.3 skey.3 rip.3 \ + skey.3 sevenbit.3 skey.3 skey_authenticate.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_set_algorithm.3 \ + skey.3 skey_unlock.3 skey.3 skeychallenge.3 skey.3 skeygetnext.3 \ + skey.3 skeylookup.3 skey.3 skeyverify.3 skey.3 skeyzero.3 \ + skey.3 skipspace.3 includes: @cd ${.CURDIR}; for i in $(HDRS); do \ diff --git a/lib/libskey/skey.3 b/lib/libskey/skey.3 new file mode 100644 index 00000000000..6960a2b0baf --- /dev/null +++ b/lib/libskey/skey.3 @@ -0,0 +1,392 @@ +.\" $OpenBSD: skey.3,v 1.1 2001/06/23 21:34:40 millert Exp $ +.\" +.\" Copyright (c) 2001 Todd C. Miller <Todd.Miller@courtesan.com> +.\" All rights reserved. +.\" +.\" 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. The name of the author may not be used to endorse or promote products +.\" derived from this software without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED ``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 AUTHOR 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 June 21, 2001 +.Dt SKEY 3 +.Os +.Sh NAME +.Nm atob8, +.Nm backspace, +.Nm btoa8, +.Nm btoe, +.Nm etob, +.Nm f, +.Nm htoi, +.Nm keycrunch, +.Nm put8, +.Nm readpass, +.Nm readskey, +.Nm rip, +.Nm sevenbit, +.Nm skey_authenticate, +.Nm skey_get_algorithm +.Nm skey_haskey, +.Nm skey_keyinfo, +.Nm skey_passcheck, +.Nm skey_set_algorithm, +.Nm skey_unlock, +.Nm skeychallenge, +.Nm skeygetnext, +.Nm skeylookup, +.Nm skeyverify, +.Nm skeyzero, +.Nm skipspace +.Nd S/Key library functions +.Sh SYNOPSIS +.Fd #include <skey.h> +.Ft int +.Fn atob8 "char *out" "char *in" +.Ft void +.Fn backspace "char *buf" +.Ft int +.Fn btoa8 "char *out" "char *in" +.Ft char * +.Fn btoe "char *engout" "char *c" +.Ft int +.Fn etob "char *out" "char *e" +.Ft void +.Fn f "char *x" +.Ft int +.Fn htoi "int h" +.Ft int +.Fn keycrunch "char *result" "char *seed" "char *passwd" +.Ft char * +.Fn put8 "char *out" "char *s" +.Ft char * +.Fn readpass "char *buf" "int n" +.Ft char * +.Fn readskey "char *buf" "int n" +.Ft void +.Fn rip "char *buf" +.Ft void +.Fn sevenbit "char *s" +.Ft int +.Fn skey_authenticate "char *user" +.Ft const char * +.Fn skey_get_algorithm "void" +.Ft int +.Fn skey_haskey "char *user" +.Ft char * +.Fn skey_keyinfo "char *user" +.Ft int +.Fn skey_passcheck "char *user" "char *passwd" +.Ft char * +.Fn skey_set_algorithm "char *new" +.Ft int +.Fn skey_unlock "struct skey *rec" +.Ft int +.Fn skeychallenge "struct skey *rec" "char *user" "char *buf" +.Ft int +.Fn skeygetnext "struct skey *rec" +.Ft int +.Fn skeylookup "struct skey *rec" "char *user" +.Ft int +.Fn skeyverify "struct skey *rec" "char *response" +.Ft int +.Fn skeyzero "struct skey *" "char *user" +.Ft char * +.Fn skipspace "char *" +.Sh DESCRIPTION +These functions implement the S/Key one time password authentication +mechanism. +.Pp +The +.Fn atob8 +function converts the 16-byte hex string +.Fa in +to an 8-byte binary array stored in +.Fa out . +The +.Fn atob8 +function returns 0 on success and -1 if an invalid hex character is encountered. +.Pp +The +.Fn backspace +function removes backspaced over characters from +.Fa buf . +Note that +.Fn backspace +assumes the actual backspace character is 0x8 (^H). +.Pp +The +.Fn btoa8 +function converts the 8-byte binary array +.Fa in +to a 16-byte string of hex digits stored in +.Fa out . +The +.Fn btoa8 +function returns 0 on success and -1 if an error occurred. +.Pp +The +.Fn btoe +function encodes the 8 bytes in +.Fa c +into a string of 6 english words, stored in +.Fa engout . +The caller must supply enough space (30 bytes including the final NUL) +to store the words. +The +.Fn btoe +function returns +.Fa engout . +.Pp +The +.Fn etob +function converts the 6 english words in +.Fa e +into an 8-byte binary representation. +The +.Fn 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. +.Pp +The +.Fn f +function is a one-way hash that overwrites the 8-byte input buffer +.Fa x +with the hashed result. +.Pp +The +.Fn htoi +function converts a single hex digit +.Fa h +to an integer. +The +.Fn htoi +function returns the converted integer on success or -1 if +.Fa h +not a valid hex digit. +.Pp +The +.Fn keycrunch +function concatenates the +.Fa seed +and +.Fa passwd , +runs them through a hash function and collapses the +.Fa result +to 64 bits. +The +.Fn keycrunch +function returns 0 on success or -1 if there is a memory allocation failure. +.Pp +The +.Fn put8 +function converts the 8 bytes stored in +.Fa s +into a series of 4 16-bit hex digit stored in +.Fa out . +There must be at least 20 bytes (including the NUL) in the output buffer, +.Fa out . +The +.Fn put8 +function returns +.Fa out . +.Pp +The +.Fn readpass +function reads up to +.Fa n +characters from standard input with echo turned off, converting the +resulting string to 7 bits, storing the result in +.Fa buf . +The +.Fn readpass +function returns +.Fa buf . +.Pp +The +.Fn readskey +function reads up to +.Fa n +characters from standard input with echo turned on, converting the +resulting string to 7 bits, storing the result in +.Fa buf . +The +.Fn readskey +function returns +.Fa buf . +.Pp +The +.Fn rip +function strips trailing linefeeds and carriage returns from +.Fa buf . +.Pp +The +.Fn sevenbit +function strips the high bit from each character in +.Fa s , +converting the characters to seven bit +.Tn ASCII . +.Pp +The +.Fn skey_authenticate +function presents the +.Fa user +with an S/Key challenge and authenticates the response. +The +.Fn skey_authenticate +function returns 0 if authentication is successful or -1 if not. +.Pp +The +.Fn skey_get_algorithm +function returns a string corresponding to the hash algorithm for +the current user. +The default algorithm is +.Dq md5 . +.Pp +The +.Fn skey_haskey +function returns 0 if the +.Fa user +exists in the S/Key database, 1 if the user does not exist, or -1 +if there was an error reading the database. +.Pp +The +.Fn skey_keyinfo +function returns a string containing the current sequence number and seed for +.Fa user . +The returned string points to internal static storage that will be +overwritten by subsequent calls to +.Fn skey_keyinfo . +.Pp +The +.Fn skey_passcheck +function check a +.Fa user +and +.Fa passwd +pair against the S/Key database. +It returns 0 on successful authentication or -1 on failure. +.Pp +The +.Fn skey_set_algorithm +function sets the user's hash algorithm based on the string +.Fa new . +The +.Fn skey_set_algorithm +function returns the specified algorithm if it is supported, +or the null pointer if the hash algorithm is not supported. +.Pp +The +.Fn skey_unlock +function unlocks the record in the S/Key database specified by +.Fa rec . +The +.Fn 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. +.Pp +The +.Fn skeychallenge +function stores the (potentially fake) S/Key challenge for +.Fa user +in +.Fa buf . +It also fills in the skey struct +.Fa rec +and locks the user's record in the S/Key database. +The +.Fn 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. +.Pp +The +.Fn skeygetnext +function stores the next record in the S/Key database in +.Fa rec +and locks that record in the S/Key database. +The +.Fn 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 +.Fn 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. +.Pp +The +.Fn skeylookup +function looks up the specified +.Fa user +in the S/Key database then fills in the skey struct +.Fa rec +and locks the user's record in the database. +The +.Fn skeylookup +function returns 0 on success, 1 if +.Fa 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. +.Pp +The +.Fn skeyverify +function verifies the user's +.Fa response +based on the S/Key record +.Fa 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 +.Fn skeyverify . +.Pp +The +.Fn skeyzero +function zeroes out the entry in the S/Key database specified by +.Fa rec +and +.Fa user . +The +.Fn skeyzero +function returns 0 on success and -1 if there was an error updating +the database. +The database is always closed by a call to +.Fn skeyzero . +.Sh SEE ALSO +.Xr skey 1 , +.Xr skeyinit 1 +.Sh STANDARDS +There is no standard API for S/Key. +The de facto standard is the free S/Key distribution released by Bellcore. +.Pp +The following functions are extensions and do not appear in +the original Bellcore S/Key distribution: +.Fn readskey , +.Fn skey_authenticate , +.Fn skey_get_algorithm , +.Fn skey_haskey , +.Fn skey_keyinfo , +.Fn skey_passcheck , +.Fn skey_set_algorithm , +.Fn skey_unlock , +.Fn skeyzero . |