1.\" $OpenBSD: crypt_checkpass.3,v 1.5 2014/12/02 07:39:58 schwarze Exp $ 2.\" 3.\" Copyright (c) 2014 Ted Unangst <tedu@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: December 2 2014 $ 18.Dt CRYPT_CHECKPASS 3 19.Os 20.Sh NAME 21.Nm crypt_checkpass , 22.Nm crypt_newhash 23.Nd password hashing 24.Sh SYNOPSIS 25.In unistd.h 26.Ft int 27.Fn crypt_checkpass "const char *password" "const char *hash" 28.Ft int 29.Fn crypt_newhash "const char *password" "const char *pref" "char *hash" "size_t hashsize" 30.Sh DESCRIPTION 31The 32.Fn crypt_checkpass 33function is provided to simplify checking a user's password. 34If both the 35.Fa hash 36and the 37.Fa password 38are the empty string, authentication 39is a success. 40Otherwise, the 41.Fa password 42is hashed and compared to the provided 43.Fa hash . 44If the 45.Fa hash 46is 47.Dv NULL , 48authentication will always fail, but a default 49amount of work is performed to simulate the hashing operation. 50A successful match will return 0. 51A failure will return \-1 and set 52.Xr errno 2 . 53.Pp 54The 55.Fn crypt_newhash 56function is provided to simplify the creation of new password hashes. 57The provided 58.Fa password 59is randomly salted and hashed and stored in 60.Fa hash . 61The 62.Fa pref 63argument identifies the preferred hashing algorithm and parameters. 64Refer to 65.Xr login.conf 5 . 66.Sh RETURN VALUES 67.Rv -std crypt_checkpass crypt_newhash 68.Sh ERRORS 69The 70.Fn crypt_checkpass 71function sets 72.Va errno 73to 74.Er EACCESS 75when authentication fails. 76.Pp 77The 78.Fn crypt_newhash 79function sets 80.Va errno 81to 82.Er EINVAL 83or any of the errors specified for 84.Xr strtonum 3 85if 86.Fa pref 87is unsupported. 88.Sh SEE ALSO 89.Xr crypt 3 , 90.Xr login.conf 5 , 91.Xr passwd 5 92.Sh HISTORY 93The function 94.Fn crypt_checkpass 95first appeared in 96.Ox 5.6 , 97and 98.Fn crypt_newhash 99in 100.Ox 5.7 . 101.Sh AUTHORS 102.An Ted Unangst Aq Mt tedu@openbsd.org 103