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 .\"
  27 .Dd December 22, 1996
  28 .Dt SKEY 3
  29 .Os
  30 .Sh NAME
  31 .Nm skeylookup ,
  32 .Nm skeyverify ,
  33 .Nm skeychallenge ,
  34 .Nm skeyinfo ,
  35 .Nm skeyaccess ,
  36 .Nm skey_getpass ,
  37 .Nm skey_crypt
  38 .Nd library routines for S/Key password control table access
  39 .Sh LIBRARY
  40 .Lb libskey
  41 .Sh SYNOPSIS
  42 .Fd #include <stdio.h>
  43 .Fd #include <skey.h>
  44 .Ft int
  45 .Fn skeylookup "struct skey *mp" "const char *name"
  46 .Ft int
  47 .Fn skeyverify "struct skey *mp" "char *response"
  48 .Ft int
  49 .Fn skeychallenge "struct skey *mp" "const char *name" "char *challenge"
  50 .Ft int
  51 .Fn skeyinfo "struct skey *mp" "const char *name" "char *ss"
  52 .Ft int
  53 .Fn skeyaccess "char *user" "const char *port" "const char *host" "const char *addr"
  54 .Ft char *
  55 .Fn skey_getpass "const char *prompt" "struct passwd *pwd" "int pwok"
  56 .Ft const char *
  57 .Fn skey_crypt "char *pp" "char *salt" "struct passwd *pwd" "int pwok"
  58 .Sh DESCRIPTION
  59 These routes support the S/Key one time password system used for
  60 accessing computer systems.
  61 See
  62 .Xr skey 1
  63 for more information about the S/Key system itself.
  64 .Pp
  65 .Pp
  66 .Fn skeylookup
  67 finds an entry in the one-time password database.
  68 On success (an entry is found corresponding to the given name),
  69 they skey structure passed by the caller is filled and 0 is
  70 returned, with the file read/write pointer positioned at the
  71 beginning of the record found.
  72 If no entry is found corresponding to the given name, the file
  73 read/write pointer is positioned at end of file and the routine
  74 returns 1.
  75 If the database cannot be opened or an access error occurs,
  76 .Fn skeylookup
  77 returns -1.
  78 .Pp
  79 The
  80 .Fn skeyinfo
  81 function looks up skey info for user 'name'.
  82 If successful, the caller's skey structure is filled and
  83 .Fn skeyinfo
  84 returns 0.
  85 If an optional challenge string buffer is given, it is updated.
  86 If unsuccessful (e.g. if the name is unknown, or the database
  87 cannot be accessed) -1 is returned.
  88 .Pp
  89 .Fn skeychallenge
  90 returns an skey challenge string for 'name'.
  91 If successful, the caller's skey structure is filled, and
  92 the function returns 0, with the file read/write pointer
  93 left at the start of the record.
  94 If unsuccessful (ie. the name was not found), the function
  95 returns -1 and the database is closed.
  96 .Pp
  97 .Fn skeyverify
  98 verifies a response to an s/key challenge.
  99 If this function returns 0, the verify was successful and
 100 the database was updated.
 101 If 1 is returned, the verify failed and the database remains
 102 unchanged.
 103 If -1 is returned, some sort of error occurred with the database,
 104 and the database is left unchanged.
 105 The s/key database is always closed by this call.
 106 .Pp
 107 The
 108 .Fn skey_getpass
 109 function may be used to read regular or s/key passwords.
 110 The prompt to use is passed to the function, along with the
 111 full (secure) struct passwd for the user to be verified.
 112 .Fn skey_getpass
 113 uses the standard library getpass on the first attempt at
 114 retrieving the user's password, and if that is blank, turns
 115 echo back on and retrieves the S/Key password.
 116 In either case, the entered string is returned back to the
 117 caller.
 118 .Pp
 119 The
 120 .Fn skey_crypt
 121 is a wrapper function for the standard library
 122 .Xr crypt 3 ,
 123 which returns the encrypted UNIX password if either the given
 124 s/key or regular passwords are ok.
 125 .Fn skey_crypt
 126 first attempts verification of the given password via the skey
 127 method, and will return the encrypted password from the
 128 passwd structure if it can be verified, as though the user had
 129 actually entered the correct UNIX password.
 130 If s/key password verification does not work, then the password
 131 is encrypted in the usual way and the result passed back to the
 132 caller.
 133 If the passwd structure pointer is NULL,
 134 .Fn skey_crypt
 135 returns a non-NULL string which could not possibly be a valid
 136 UNIX password (namely, a string containing ":").
 137 .Pp
 138 The
 139 .Fn skeyaccess
 140 function determines whether traditional UNIX (non-S/Key) passwords
 141 are permitted for any combination of user name, group member,
 142 terminal port, host name, and network.  If UNIX passwords are allowed,
 143 .Fn skeyaccess
 144 returns a non-zero value.  If UNIX passwords are not allowed, it
 145 returns 0.  See
 146 .Xr skey.access 5
 147 for more information on the layout and structure of the
 148 skey.access configuration file which this function uses.
 149 .Sh RETURN VALUES
 150 See above.
 151 .Sh SEE ALSO
 152 .Xr skey 1 ,
 153 .Xr skey.access 5
 154 .Sh BUGS
 155 No advisory locking is done on the s/key database to guard against
 156 simultaneous access from multiple processes.
 157 This is not normally a problem when keys are added to or updated
 158 in the file, but may be problematic when keys are removed.
 159 .Sh AUTHORS
 160 .An Phil Karn ,
 161 .An Neil M. Haller ,
 162 .An John S. Walden ,
 163 .An Scott Chasin