1.\" $OpenBSD: crypt_checkpass.3,v 1.9 2015/07/23 22:20:02 tedu 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: July 23 2015 $ 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. 64Possible values are: 65.Bl -tag -width Ds 66.It Dq bcrypt,<rounds> 67The bcrypt algorithm, where the value of rounds can be between 4 and 31 and 68specifies the base 2 logarithm of the number of rounds. 69The special rounds value 70.Sq a 71automatically selects rounds based on system performance. 72.El 73.Sh RETURN VALUES 74.Rv -std crypt_checkpass crypt_newhash 75.Sh ERRORS 76The 77.Fn crypt_checkpass 78function sets 79.Va errno 80to 81.Er EACCESS 82when authentication fails. 83.Pp 84The 85.Fn crypt_newhash 86function sets 87.Va errno 88to 89.Er EINVAL 90if 91.Fa pref 92is unsupported. 93.Sh SEE ALSO 94.Xr crypt 3 , 95.Xr login.conf 5 , 96.Xr passwd 5 97.Sh HISTORY 98The function 99.Fn crypt_checkpass 100first appeared in 101.Ox 5.6 , 102and 103.Fn crypt_newhash 104in 105.Ox 5.7 . 106.Sh AUTHORS 107.An Ted Unangst Aq Mt tedu@openbsd.org 108