1.\" $OpenBSD: skey.3,v 1.12 2007/05/31 19:19:37 jmc Exp $ 2.\" 3.\" Copyright (c) 2001 Todd C. Miller <Todd.Miller@courtesan.com> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: May 31 2007 $ 18.Dt SKEY 3 19.Os 20.Sh NAME 21.Nm atob8 , 22.Nm backspace , 23.Nm btoa8 , 24.Nm btoe , 25.Nm etob , 26.Nm f , 27.Nm htoi , 28.Nm keycrunch , 29.Nm put8 , 30.Nm readpass , 31.Nm readskey , 32.Nm rip , 33.Nm sevenbit , 34.Nm skey_authenticate , 35.Nm skey_get_algorithm , 36.Nm skey_haskey , 37.Nm skey_keyinfo , 38.Nm skey_passcheck , 39.Nm skey_set_algorithm , 40.Nm skey_unlock , 41.Nm skeychallenge , 42.Nm skeychallenge2 , 43.Nm skeygetnext , 44.Nm skeylookup , 45.Nm skeyverify , 46.Nm skipspace 47.Nd S/Key library functions 48.Sh SYNOPSIS 49.Fd #include <skey.h> 50.Ft int 51.Fn atob8 "char *out" "char *in" 52.Ft void 53.Fn backspace "char *buf" 54.Ft int 55.Fn btoa8 "char *out" "char *in" 56.Ft char * 57.Fn btoe "char *engout" "char *c" 58.Ft int 59.Fn etob "char *out" "char *e" 60.Ft void 61.Fn f "char *x" 62.Ft int 63.Fn htoi "int h" 64.Ft int 65.Fn keycrunch "char *result" "char *seed" "char *passwd" 66.Ft char * 67.Fn put8 "char *out" "char *s" 68.Ft char * 69.Fn readpass "char *buf" "int n" 70.Ft char * 71.Fn readskey "char *buf" "int n" 72.Ft void 73.Fn rip "char *buf" 74.Ft void 75.Fn sevenbit "char *s" 76.Ft int 77.Fn skey_authenticate "char *user" 78.Ft const char * 79.Fn skey_get_algorithm "void" 80.Ft int 81.Fn skey_haskey "char *user" 82.Ft char * 83.Fn skey_keyinfo "char *user" 84.Ft int 85.Fn skey_passcheck "char *user" "char *passwd" 86.Ft char * 87.Fn skey_set_algorithm "char *new" 88.Ft int 89.Fn skey_unlock "struct skey *rec" 90.Ft int 91.Fn skeychallenge "struct skey *rec" "char *user" "char *buf" 92.Ft int 93.Fn skeychallenge2 "int fd" "struct skey *rec" "char *user" "char *buf" 94.Ft int 95.Fn skeygetnext "struct skey *rec" 96.Ft int 97.Fn skeylookup "struct skey *rec" "char *user" 98.Ft int 99.Fn skeyverify "struct skey *rec" "char *response" 100.Ft char * 101.Fn skipspace "char *" 102.Sh DESCRIPTION 103These functions implement the S/Key one time password authentication 104mechanism. 105.Pp 106The 107.Fn atob8 108function converts the 16-byte hex string 109.Fa in 110to an 8-byte binary array stored in 111.Fa out . 112The 113.Fn atob8 114function returns 0 on success and \-1 if an invalid hex character is encountered. 115.Pp 116The 117.Fn backspace 118function removes backspaced over characters from 119.Fa buf . 120Note that 121.Fn backspace 122assumes the actual backspace character is 0x8 (^H). 123.Pp 124The 125.Fn btoa8 126function converts the 8-byte binary array 127.Fa in 128to a 16-byte string of hex digits stored in 129.Fa out ; 130the caller must supply enough space (17 bytes including the final NUL). 131The 132.Fn btoa8 133function returns 0 on success and \-1 if an error occurred. 134.Pp 135The 136.Fn btoe 137function encodes the 8 bytes in 138.Fa c 139into a string of 6 English words, stored in 140.Fa engout . 141The caller must supply enough space (30 bytes including the final NUL) 142to store the words. 143The 144.Fn btoe 145function returns 146.Fa engout . 147.Pp 148The 149.Fn etob 150function converts the 6 English words in 151.Fa e 152into an 8-byte binary representation. 153The 154.Fn etob 155function returns 1 if the words are all in the database and parity is correct, 1560 if a word is not in the database, \-1 if the number of words is incorrect, 157or \-2 if there is a parity error. 158.Pp 159The 160.Fn f 161function is a one-way hash that overwrites the 8-byte input buffer 162.Fa x 163with the hashed result. 164.Pp 165The 166.Fn htoi 167function converts a single hex digit 168.Fa h 169to an integer. 170The 171.Fn htoi 172function returns the converted integer on success or \-1 if 173.Fa h 174not a valid hex digit. 175.Pp 176The 177.Fn keycrunch 178function concatenates the 179.Fa seed 180and 181.Fa passwd , 182runs them through a hash function and collapses the 183.Fa result 184to 64 bits. 185The 186.Fn keycrunch 187function returns 0 on success or \-1 if there is a memory allocation failure. 188.Pp 189The 190.Fn put8 191function converts the 8 bytes stored in 192.Fa s 193into a series of 4 16-bit hex digit stored in 194.Fa out . 195There must be at least 20 bytes (including the NUL) in the output buffer, 196.Fa out . 197The 198.Fn put8 199function returns 200.Fa out . 201.Pp 202The 203.Fn readpass 204function reads up to 205.Fa n 206characters from standard input with echo turned off, converting the 207resulting string to 7 bits, storing the result in 208.Fa buf . 209The 210.Fn readpass 211function returns 212.Fa buf . 213.Pp 214The 215.Fn readskey 216function reads up to 217.Fa n 218characters from standard input with echo turned on, converting the 219resulting string to 7 bits, storing the result in 220.Fa buf . 221The 222.Fn readskey 223function returns 224.Fa buf . 225.Pp 226The 227.Fn rip 228function strips trailing linefeeds and carriage returns from 229.Fa buf . 230.Pp 231The 232.Fn sevenbit 233function strips the high bit from each character in 234.Fa s , 235converting the characters to seven bit 236.Tn ASCII . 237.Pp 238The 239.Fn skey_authenticate 240function presents the 241.Fa user 242with an S/Key challenge and authenticates the response. 243The 244.Fn skey_authenticate 245function returns 0 if authentication is successful or \-1 if not. 246.Pp 247The 248.Fn skey_get_algorithm 249function returns a string corresponding to the hash algorithm for 250the current user. 251The default algorithm is 252.Dq md5 . 253.Pp 254The 255.Fn skey_haskey 256function returns 0 if the 257.Fa user 258exists in the S/Key database, 1 if the user does not exist, or \-1 259if there was an error reading the database. 260.Pp 261The 262.Fn skey_keyinfo 263function returns a string containing the current sequence number and seed for 264.Fa user . 265The returned string points to internal static storage that will be 266overwritten by subsequent calls to 267.Fn skey_keyinfo . 268.Pp 269The 270.Fn skey_passcheck 271function checks a 272.Fa user 273and 274.Fa passwd 275pair against the S/Key database. 276It returns 0 on successful authentication or \-1 on failure. 277.Pp 278The 279.Fn skey_set_algorithm 280function sets the user's hash algorithm based on the string 281.Fa new . 282The 283.Fn skey_set_algorithm 284function returns the specified algorithm if it is supported, 285or the null pointer if the hash algorithm is not supported. 286.Pp 287The 288.Fn skey_unlock 289function unlocks the record in the S/Key database specified by 290.Fa rec . 291The 292.Fn skey_unlock 293function returns 0 on success or \-1 on failure. 294Either way, the S/Key database is not closed nor is the database 295file pointer affected. 296.Pp 297The 298.Fn skeychallenge 299function stores the (potentially fake) S/Key challenge for 300.Fa user 301in 302.Fa buf , 303which is at least SKEY_MAX_CHALLENGE bytes long. 304It also fills in the skey struct 305.Fa rec 306and locks the user's record in the S/Key database. 307The 308.Fn skeychallenge 309function returns 0 on success or \-1 on failure. 310On success the S/Key database remains open and the read/write file 311pointer is set to the beginning of the record. 312.Pp 313The 314.Fn skeychallenge2 315function is identical to 316.Fn skeychallenge 317except that instead of opening the user's entry in the S/Key database, 318the open file referenced by 319.Ar fd 320is used instead. 321When 322.Ar fd 323is \-1, the behavior is equivalent to 324.Fn skeychallenge . 325.Pp 326The 327.Fn skeygetnext 328function stores the next record in the S/Key database in 329.Fa rec 330and locks that record in the S/Key database. 331The 332.Fn skeygetnext 333function returns 0 on success, 1 if there are no more entries, 334or \-1 if there was an error accessing the S/Key database. 335The S/Key database remains open after a call to 336.Fn skeygetnext . 337If no error was encountered accessing the S/Key database, the read/write 338file pointer is set to the beginning of the record or at EOF if 339there are no more records. 340.br 341Because it exposes other users' S/Key records, only the superuser may use 342.Fn skeygetnext . 343.Pp 344The 345.Fn skeylookup 346function looks up the specified 347.Fa user 348in the S/Key database then fills in the skey struct 349.Fa rec 350and locks the user's record in the database. 351The 352.Fn skeylookup 353function returns 0 on success, 1 if 354.Fa user 355was not found, or \-1 if there was an error accessing the S/Key database. 356If no error was encountered accessing the S/Key database, the read/write 357file pointer is set to the beginning of the record. 358.Pp 359The 360.Fn skeyverify 361function verifies the user's 362.Fa response 363based on the S/Key record 364.Fa rec . 365It returns 0 on success (updating the database), 1 on failure, or 366\-1 if there was an error accessing the database. 367The database is always closed by a call to 368.Fn skeyverify . 369.Sh SEE ALSO 370.Xr skey 1 , 371.Xr skeyinit 1 372.Sh STANDARDS 373There is no standard API for S/Key. 374The de facto standard is the free S/Key distribution released by Bellcore. 375.Pp 376The following functions are extensions and do not appear in 377the original Bellcore S/Key distribution: 378.Fn readskey , 379.Fn skey_authenticate , 380.Fn skey_get_algorithm , 381.Fn skey_haskey , 382.Fn skey_keyinfo , 383.Fn skey_passcheck , 384.Fn skey_set_algorithm , 385.Fn skey_unlock . 386.Pp 387S/Key is a Trademark of Bellcore. 388