lib/libskey/skey.3

   1 .\" Copyright (c) 1996
   2 .\" David L. Nugent. All Rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY DAVID L. NUGENT AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL DAVID L. NUGENT OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .\" $FreeBSD: src/lib/libskey/skey.3,v 1.10.2.1 2000/04/22 16:36:00 phantom Exp $
  26 .\" $DragonFly: src/lib/libskey/skey.3,v 1.5 2006/05/26 19:39:38 swildner Exp $
  27 .\"
  28 .Dd December 22, 1996
  29 .Dt SKEY 3
  30 .Os
  31 .Sh NAME
  32 .Nm skeylookup ,
  33 .Nm skeyverify ,
  34 .Nm skeychallenge ,
  35 .Nm skeyinfo ,
  36 .Nm skeyaccess ,
  37 .Nm skey_getpass ,
  38 .Nm skey_crypt
  39 .Nd library routines for S/Key password control table access
  40 .Sh LIBRARY
  41 .Lb libskey
  42 .Sh SYNOPSIS
  43 .In stdio.h
  44 .In skey.h
  45 .Ft int
  46 .Fn skeylookup "struct skey *mp" "const char *name"
  47 .Ft int
  48 .Fn skeyverify "struct skey *mp" "char *response"
  49 .Ft int
  50 .Fn skeychallenge "struct skey *mp" "const char *name" "char *challenge"
  51 .Ft int
  52 .Fn skeyinfo "struct skey *mp" "const char *name" "char *ss"
  53 .Ft int
  54 .Fn skeyaccess "char *user" "const char *port" "const char *host" "const char *addr"
  55 .Ft char *
  56 .Fn skey_getpass "const char *prompt" "struct passwd *pwd" "int pwok"
  57 .Ft const char *
  58 .Fn skey_crypt "char *pp" "char *salt" "struct passwd *pwd" "int pwok"
  59 .Sh DESCRIPTION
  60 These routes support the S/Key one time password system used for
  61 accessing computer systems.
  62 See
  63 .Xr skey 1
  64 for more information about the S/Key system itself.
  65 .Pp
  66 .Pp
  67 .Fn skeylookup
  68 finds an entry in the one-time password database.
  69 On success (an entry is found corresponding to the given name),
  70 they skey structure passed by the caller is filled and 0 is
  71 returned, with the file read/write pointer positioned at the
  72 beginning of the record found.
  73 If no entry is found corresponding to the given name, the file
  74 read/write pointer is positioned at end of file and the routine
  75 returns 1.
  76 If the database cannot be opened or an access error occurs,
  77 .Fn skeylookup
  78 returns -1.
  79 .Pp
  80 The
  81 .Fn skeyinfo
  82 function looks up skey info for user 'name'.
  83 If successful, the caller's skey structure is filled and
  84 .Fn skeyinfo
  85 returns 0.
  86 If an optional challenge string buffer is given, it is updated.
  87 If unsuccessful (e.g. if the name is unknown, or the database
  88 cannot be accessed) -1 is returned.
  89 .Pp
  90 .Fn skeychallenge
  91 returns an skey challenge string for 'name'.
  92 If successful, the caller's skey structure is filled, and
  93 the function returns 0, with the file read/write pointer
  94 left at the start of the record.
  95 If unsuccessful (ie. the name was not found), the function
  96 returns -1 and the database is closed.
  97 .Pp
  98 .Fn skeyverify
  99 verifies a response to an s/key challenge.
 100 If this function returns 0, the verify was successful and
 101 the database was updated.
 102 If 1 is returned, the verify failed and the database remains
 103 unchanged.
 104 If -1 is returned, some sort of error occurred with the database,
 105 and the database is left unchanged.
 106 The s/key database is always closed by this call.
 107 .Pp
 108 The
 109 .Fn skey_getpass
 110 function may be used to read regular or s/key passwords.
 111 The prompt to use is passed to the function, along with the
 112 full (secure) struct passwd for the user to be verified.
 113 .Fn skey_getpass
 114 uses the standard library getpass on the first attempt at
 115 retrieving the user's password, and if that is blank, turns
 116 echo back on and retrieves the S/Key password.
 117 In either case, the entered string is returned back to the
 118 caller.
 119 .Pp
 120 The
 121 .Fn skey_crypt
 122 is a wrapper function for the standard library
 123 .Xr crypt 3 ,
 124 which returns the encrypted UNIX password if either the given
 125 s/key or regular passwords are ok.
 126 .Fn skey_crypt
 127 first attempts verification of the given password via the skey
 128 method, and will return the encrypted password from the
 129 passwd structure if it can be verified, as though the user had
 130 actually entered the correct UNIX password.
 131 If s/key password verification does not work, then the password
 132 is encrypted in the usual way and the result passed back to the
 133 caller.
 134 If the passwd structure pointer is NULL,
 135 .Fn skey_crypt
 136 returns a non-NULL string which could not possibly be a valid
 137 UNIX password (namely, a string containing ":").
 138 .Pp
 139 The
 140 .Fn skeyaccess
 141 function determines whether traditional UNIX (non-S/Key) passwords
 142 are permitted for any combination of user name, group member,
 143 terminal port, host name, and network.  If UNIX passwords are allowed,
 144 .Fn skeyaccess
 145 returns a non-zero value.  If UNIX passwords are not allowed, it
 146 returns 0.  See
 147 .Xr skey.access 5
 148 for more information on the layout and structure of the
 149 skey.access configuration file which this function uses.
 150 .Sh RETURN VALUES
 151 See above.
 152 .Sh SEE ALSO
 153 .Xr skey 1 ,
 154 .Xr skey.access 5
 155 .Sh AUTHORS
 156 .An Phil Karn ,
 157 .An Neil M. Haller ,
 158 .An John S. Walden ,
 159 .An Scott Chasin
 160 .Sh BUGS
 161 No advisory locking is done on the s/key database to guard against
 162 simultaneous access from multiple processes.
 163 This is not normally a problem when keys are added to or updated
 164 in the file, but may be problematic when keys are removed.