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.3 2005/08/01 01:49:16 swildner Exp $
39 .Nd library routines for S/Key password control table access
43 .Fd #include <stdio.h>
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 UNIX password if either the given
125 s/key or regular passwords are ok.
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
134 If the passwd structure pointer is NULL,
136 returns a non-NULL string which could not possibly be a valid
137 UNIX password (namely, a string containing ":").
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,
145 returns a non-zero value. If UNIX passwords are not allowed, it
148 for more information on the layout and structure of the
149 skey.access configuration file which this function uses.
156 No advisory locking is done on the s/key database to guard against
157 simultaneous access from multiple processes.
158 This is not normally a problem when keys are added to or updated
159 in the file, but may be problematic when keys are removed.