lib/libskey/skey.3

   1 .\"     $NetBSD: skey.3,v 1.8 2003/06/06 13:42:50 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Gregory McGarry.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd November 10, 2001
  31 .Dt SKEY 3
  32 .Os
  33 .Sh NAME
  34 .Nm skey ,
  35 .Nm skeychallenge ,
  36 .Nm skeylookup ,
  37 .Nm skeygetnext ,
  38 .Nm skeyverify ,
  39 .Nm skeyzero ,
  40 .Nm getskeyprompt ,
  41 .Nm skey_set_algorithm ,
  42 .Nm skey_get_algorithm ,
  43 .Nm skey_haskey ,
  44 .Nm skey_keyinfo ,
  45 .Nm skey_passcheck ,
  46 .Nm skey_authenticate
  47 .Nd one-time password (OTP) library
  48 .Sh LIBRARY
  49 S/key One-Time Password Library (libskey, -lskey)
  50 .Sh SYNOPSIS
  51 .In skey.h
  52 .Ft int
  53 .Fn skeychallenge "struct skey *mp" "const char *name" "char *ss" \
  54 "size_t sslen"
  55 .Ft int
  56 .Fn skeylookup "struct skey *mp" "const char *name"
  57 .Ft int
  58 .Fn skeygetnext "struct skey *mp"
  59 .Ft int
  60 .Fn skeyverify "struct skey *mp" "char *response"
  61 .Ft int
  62 .Fn skeyzero "struct skey *mp" "char *response"
  63 .Ft int
  64 .Fn getskeyprompt "struct skey *mp" "char *name" "char *prompt"
  65 .Ft const char *
  66 .Fn skey_set_algorithm "const char *new"
  67 .Ft const char *
  68 .Fn skey_get_algorithm "void"
  69 .Ft int
  70 .Fn skey_haskey "const char *username"
  71 .Ft const char *
  72 .Fn skey_keyinfo "const char *username"
  73 .Ft int
  74 .Fn skey_passcheck "const char *username" "char *passwd"
  75 .Ft int
  76 .Fn skey_authenticate "const char *username"
  77 .Ft void
  78 .Fn f "char *x"
  79 .Ft int
  80 .Fn keycrunch "char *result" "const char *seed" "const char *passwd"
  81 .Ft void
  82 .Fn rip "char *buf"
  83 .Ft char *
  84 .Fn readpass "char *buf " "int n"
  85 .Ft char *
  86 .Fn readskey "char *buf" "int n"
  87 .Ft int
  88 .Fn atob8 "char *out" "const char *in"
  89 .Ft int
  90 .Fn btoa8 "char *out" "const char *in"
  91 .Ft int
  92 .Fn htoi "int c"
  93 .Ft const char *
  94 .Fn skipspace "const char *cp"
  95 .Ft void
  96 .Fn backspace "char *buf"
  97 .Ft void
  98 .Fn sevenbit "char *buf"
  99 .Ft char *
 100 .Fn btoe "char *engout" "const char *c"
 101 .Ft int
 102 .Fn etob "char *out" "const char *e"
 103 .Ft char *
 104 .Fn put8 "char *out" "const char *s"
 105 .Sh DESCRIPTION
 106 The
 107 .Nm
 108 library provides routines for accessing
 109 .Nx Ns 's
 110 one-time password (OTP) authentication system.
 111 .Pp
 112 Most S/Key operations take a pointer to a
 113 .Em struct skey ,
 114 which should be considered as an opaque identifier.
 115 .Sh FUNCTIONS
 116 The following high-level functions are available:
 117 .Bl -tag -width compact
 118 .It Fn skeychallenge "mp" "name" "ss" "sslen"
 119 Return a S/Key challenge for user
 120 .Fa name .
 121 If successful, the caller's skey structure
 122 .Fa mp
 123 is filled and 0 is returned.
 124 If unsuccessful (e.g. if name is unknown),
 125 \-1 is returned.
 126 .It Fn skeylookup "mp" "name"
 127 Find an entry for user
 128 .Fa name
 129 in the one-time password database.
 130 Returns 0 if the entry is found and 1 if the entry is not found.
 131 If an error occurs accessing the database, \-1 is returned.
 132 .It Fn skeygetnext "mp"
 133 Get the next entry in the one-time password database.
 134 Returns 0 on success and the entry is stored in
 135 .Ar mp
 136 and 1 if no more entries are available.
 137 If an error occurs accessing the database, \-1 is returned.
 138 .It Fn skeyverify "mp" "response"
 139 Verify response
 140 .Fa response
 141 to a S/Key challenge.
 142 Returns 0 if the verification is successful and 1 if the verification failed.
 143 If an error occurs accessing the database, \-1 is returned.
 144 .It Fn skeyzero "mp" "response"
 145 Comment out user's entry in the S/Key database.
 146 Returns 0 on success and the database is updated,
 147 otherwise \-1 is returned and the database remains unchanged.
 148 .It Fn getskeyprompt "mp" "name" "prompt"
 149 Issue a S/Key challenge for user
 150 .Ar name .
 151 If successful, fill in the caller's skey structure
 152 .Fa mp
 153 and return 0.
 154 If unsuccessful (e.g. if name is unknown) \-1 is returned.
 155 .El
 156 .Pp
 157 The following lower-level functions are available:
 158 .Bl -tag -width compact
 159 .It Fn skey_set_algorithm "new"
 160 Set hash algorithm type.
 161 Valid values for
 162 .Fa new
 163 are "md4", "md5" and "sha1".
 164 .It Fn skey_get_algorithm "void"
 165 Get current hash type.
 166 .It Fn skey_haskey "username"
 167 Returns 0 if the user
 168 .Fa username
 169 exists and 1 if the user doesn't exist.
 170 Returns \-1 on file error.
 171 .It Fn skey_keyinfo "username"
 172 Returns the current sequence number and seed for user
 173 .Ar username .
 174 .It Fn skey_passcheck "username" "passwd"
 175 Checks to see if answer is the correct one to the current challenge.
 176 .It Fn skey_authenticate "username"
 177 Used when calling program will allow input of the user's response to
 178 the challenge.
 179 Returns zero on success or \-1 on failure.
 180 .El
 181 .Pp
 182 The following miscellaneous functions are available:
 183 .Bl -tag -width compact
 184 .It Fn f "x"
 185 One-way function to take 8 bytes pointed to by
 186 .Fa x
 187 and return 8 bytes in place.
 188 .It Fn keycrunch "char *result" "const char *seed" "const char *passwd"
 189 Crunch a key.
 190 .It Fn rip "buf"
 191 Strip trailing CR/LF characters from a line of text
 192 .Fa buf .
 193 .It Fn readpass "buf" "n"
 194 Read in secret passwd (turns off echo).
 195 .It Fn readskey "buf" "n"
 196 Read in an s/key OTP (does not turn off echo).
 197 .It Fn atob8 "out" "in"
 198 Convert 8-byte hex-ascii string
 199 .Fa in
 200 to binary array
 201 .Fa out .
 202 Returns 0 on success, \-1 on error.
 203 .It Fn btoa8 "out" "in"
 204 Convert 8-byte binary array
 205 .Fa in
 206 to hex-ascii string
 207 .Fa out .
 208 Returns 0 on success, \-1 on error.
 209 .It Fn htoi "int c"
 210 Convert hex digit to binary integer.
 211 .It Fn skipspace "cp"
 212 Skip leading spaces from the string
 213 .Fa cp .
 214 .It Fn backspace "buf"
 215 Remove backspaced over characters from the string
 216 .Fa buf .
 217 .It Fn sevenbit "buf"
 218 Ensure line
 219 .Fa buf
 220 is all seven bits.
 221 .It Fn btoe "engout" "c"
 222 Encode 8 bytes in
 223 .Ar c
 224 as a string of English words.
 225 Returns a pointer to a static buffer in
 226 .Fa engout .
 227 .It Fn etob "out" "e"
 228 Convert English to binary.
 229 Returns 0 if the word is not in the database, 1 if all good words and
 230 parity is valid, \-1 if badly formed input (i.e. \*[Gt] 4 char word)
 231 and -2 if words are valid but parity is wrong.
 232 .It Fn put8 "out" "s"
 233 Display 8 bytes
 234 .Fa s
 235 as a series of 16-bit hex digits.
 236 .El
 237 .Sh FILES
 238 .Bl -tag -width /usr/lib/libskey_p.a -compact
 239 .It Pa /usr/lib/libskey.a
 240 static skey library
 241 .It Pa /usr/lib/libskey.so
 242 dynamic skey library
 243 .It Pa /usr/lib/libskey_p.a
 244 static skey library compiled for profiling
 245 .El
 246 .Sh SEE ALSO
 247 .Xr skey 1 ,
 248 .Xr skeyaudit 1 ,
 249 .Xr skeyinfo 1
 250 .Sh BUGS
 251 The
 252 .Nm
 253 library functions are not re-entrant or thread-safe.
 254 .Pp
 255 The
 256 .Nm
 257 library defines many poorly named functions which pollute the name space.