1.\" $OpenBSD: skey.3,v 1.16 2019/01/25 00:19:26 millert Exp $ 2.\" 3.\" Copyright (c) 2001 Todd C. Miller <millert@openbsd.org> 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: January 25 2019 $ 18.Dt SKEYLOOKUP 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.In 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 ASCII. 236.Pp 237The 238.Fn skey_authenticate 239function presents the 240.Fa user 241with an S/Key challenge and authenticates the response. 242The 243.Fn skey_authenticate 244function returns 0 if authentication is successful or \-1 if not. 245.Pp 246The 247.Fn skey_get_algorithm 248function returns a string corresponding to the hash algorithm for 249the current user. 250The default algorithm is 251.Dq md5 . 252.Pp 253The 254.Fn skey_haskey 255function returns 0 if the 256.Fa user 257exists in the S/Key database, 1 if the user does not exist, or \-1 258if there was an error reading the database. 259.Pp 260The 261.Fn skey_keyinfo 262function returns a string containing the current sequence number and seed for 263.Fa user . 264The returned string points to internal static storage that will be 265overwritten by subsequent calls to 266.Fn skey_keyinfo . 267.Pp 268The 269.Fn skey_passcheck 270function checks a 271.Fa user 272and 273.Fa passwd 274pair against the S/Key database. 275It returns 0 on successful authentication or \-1 on failure. 276.Pp 277The 278.Fn skey_set_algorithm 279function sets the user's hash algorithm based on the string 280.Fa new . 281The 282.Fn skey_set_algorithm 283function returns the specified algorithm if it is supported, 284or the null pointer if the hash algorithm is not supported. 285.Pp 286The 287.Fn skey_unlock 288function unlocks the record in the S/Key database specified by 289.Fa rec . 290The 291.Fn skey_unlock 292function returns 0 on success or \-1 on failure. 293Either way, the S/Key database is not closed nor is the database 294file pointer affected. 295.Pp 296The 297.Fn skeychallenge 298function stores the (potentially fake) S/Key challenge for 299.Fa user 300in 301.Fa buf , 302which is at least SKEY_MAX_CHALLENGE bytes long. 303It also fills in the skey struct 304.Fa rec 305and locks the user's record in the S/Key database. 306The 307.Fn skeychallenge 308function returns 0 on success or \-1 on failure. 309On success the S/Key database remains open and the read/write file 310pointer is set to the beginning of the record. 311.Pp 312The 313.Fn skeychallenge2 314function is identical to 315.Fn skeychallenge 316except that instead of opening the user's entry in the S/Key database, 317the open file referenced by 318.Ar fd 319is used instead. 320When 321.Ar fd 322is \-1, the behavior is equivalent to 323.Fn skeychallenge . 324.Pp 325The 326.Fn skeygetnext 327function stores the next record in the S/Key database in 328.Fa rec 329and locks that record in the S/Key database. 330The 331.Fn skeygetnext 332function returns 0 on success, 1 if there are no more entries, 333or \-1 if there was an error accessing the S/Key database. 334The S/Key database remains open after a call to 335.Fn skeygetnext . 336If no error was encountered accessing the S/Key database, the read/write 337file pointer is set to the beginning of the record or at EOF if 338there are no more records. 339.br 340Because it exposes other users' S/Key records, only the superuser may use 341.Fn skeygetnext . 342.Pp 343The 344.Fn skeylookup 345function looks up the specified 346.Fa user 347in the S/Key database then fills in the skey struct 348.Fa rec 349and locks the user's record in the database. 350The 351.Fn skeylookup 352function returns 0 on success, 1 if 353.Fa user 354was not found, or \-1 if there was an error accessing the S/Key database. 355If no error was encountered accessing the S/Key database, the read/write 356file pointer is set to the beginning of the record. 357.Pp 358The 359.Fn skeyverify 360function verifies the user's 361.Fa response 362based on the S/Key record 363.Fa rec . 364It returns 0 on success (updating the database), 1 on failure, or 365\-1 if there was an error accessing the database. 366The database is always closed by a call to 367.Fn skeyverify . 368.Sh SEE ALSO 369.Xr skey 1 , 370.Xr skeyinit 1 371.Sh STANDARDS 372There is no standard API for S/Key. 373The de facto standard is the free S/Key distribution released by Bellcore. 374.Pp 375The following functions are extensions and do not appear in 376the original Bellcore S/Key distribution: 377.Fn readskey , 378.Fn skey_authenticate , 379.Fn skey_get_algorithm , 380.Fn skey_haskey , 381.Fn skey_keyinfo , 382.Fn skey_passcheck , 383.Fn skey_set_algorithm , 384.Fn skey_unlock . 385.Pp 386S/Key is a Trademark of Bellcore. 387