2 .\" David L. Nugent. All Rights reserved.
4 .\" Redistribution and use in source and binary forms, with or without
5 .\" modification, are permitted provided that the following conditions
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.
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
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.6 2007/07/30 22:11:33 swildner Exp $
39 .Nd library routines for S/Key password control table access
46 .Fn skeylookup "struct skey *mp" "const char *name"
48 .Fn skeyverify "struct skey *mp" "char *response"
50 .Fn skeychallenge "struct skey *mp" "const char *name" "char *challenge"
52 .Fn skeyinfo "struct skey *mp" "const char *name" "char *ss"
54 .Fn skeyaccess "char *user" "const char *port" "const char *host" "const char *addr"
56 .Fn skey_getpass "const char *prompt" "struct passwd *pwd" "int pwok"
58 .Fn skey_crypt "char *pp" "char *salt" "struct passwd *pwd" "int pwok"
60 These routes support the S/Key one time password system used for
61 accessing computer systems.
64 for more information about the S/Key system itself.
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
76 If the database cannot be opened or an access error occurs,
82 function looks up skey info for user 'name'.
83 If successful, the caller's skey structure is filled and
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.
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.
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
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.
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.
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
122 is a wrapper function for the standard library
124 which returns the encrypted
126 password if either the given
127 s/key or regular passwords are ok.
129 first attempts verification of the given password via the skey
130 method, and will return the encrypted password from the
131 passwd structure if it can be verified, as though the user had
132 actually entered the correct
135 If s/key password verification does not work, then the password
136 is encrypted in the usual way and the result passed back to the
138 If the passwd structure pointer is NULL,
140 returns a non-NULL string which could not possibly be a valid
142 password (namely, a string containing ":").
146 function determines whether traditional
148 (non-S/Key) passwords
149 are permitted for any combination of user name, group member,
150 terminal port, host name, and network. If
152 passwords are allowed,
154 returns a non-zero value. If
156 passwords are not allowed, it
159 for more information on the layout and structure of the
160 skey.access configuration file which this function uses.
172 No advisory locking is done on the s/key database to guard against
173 simultaneous access from multiple processes.
174 This is not normally a problem when keys are added to or updated
175 in the file, but may be problematic when keys are removed.