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 $
38 .Nd library routines for S/Key password control table access
42 .Fd #include <stdio.h>
45 .Fn skeylookup "struct skey *mp" "const char *name"
47 .Fn skeyverify "struct skey *mp" "char *response"
49 .Fn skeychallenge "struct skey *mp" "const char *name" "char *challenge"
51 .Fn skeyinfo "struct skey *mp" "const char *name" "char *ss"
53 .Fn skeyaccess "char *user" "const char *port" "const char *host" "const char *addr"
55 .Fn skey_getpass "const char *prompt" "struct passwd *pwd" "int pwok"
57 .Fn skey_crypt "char *pp" "char *salt" "struct passwd *pwd" "int pwok"
59 These routes support the S/Key one time password system used for
60 accessing computer systems.
63 for more information about the S/Key system itself.
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
75 If the database cannot be opened or an access error occurs,
81 function looks up skey info for user 'name'.
82 If successful, the caller's skey structure is filled and
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.
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.
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
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.
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.
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
121 is a wrapper function for the standard library
123 which returns the encrypted UNIX password if either the given
124 s/key or regular passwords are ok.
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
133 If the passwd structure pointer is NULL,
135 returns a non-NULL string which could not possibly be a valid
136 UNIX password (namely, a string containing ":").
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,
144 returns a non-zero value. If UNIX passwords are not allowed, it
147 for more information on the layout and structure of the
148 skey.access configuration file which this function uses.
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.