1.\" $OpenBSD: crypt_checkpass.3,v 1.12 2019/07/29 23:14:06 deraadt 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 29 2019 $ 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 simplifies 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 simplifies the creation of new password hashes. 57The provided 58.Fa password 59is randomly salted and hashed and stored in 60.Fa hash . 61The size of the available space is specified by 62.Fa hashsize , 63which should be 64.Dv _PASSWORD_LEN . 65The 66.Fa pref 67argument identifies the preferred hashing algorithm and parameters. 68Possible values are: 69.Bl -tag -width Ds 70.It Dq bcrypt,<rounds> 71The bcrypt algorithm, where the value of rounds can be between 4 and 31 and 72specifies the base 2 logarithm of the number of rounds. 73If rounds is omitted or the special value 74.Sq a , 75an appropriate number of rounds is automatically selected based on system 76performance. 77.El 78.Sh RETURN VALUES 79.Rv -std crypt_checkpass crypt_newhash 80.Sh ERRORS 81The 82.Fn crypt_checkpass 83function sets 84.Va errno 85to 86.Er EACCES 87when authentication fails. 88.Pp 89The 90.Fn crypt_newhash 91function sets 92.Va errno 93to 94.Er EINVAL 95if 96.Fa pref 97is unsupported or insufficient space is provided. 98.Sh SEE ALSO 99.Xr crypt 3 , 100.Xr login.conf 5 , 101.Xr passwd 5 102.Sh HISTORY 103The function 104.Fn crypt_checkpass 105first appeared in 106.Ox 5.6 , 107and 108.Fn crypt_newhash 109in 110.Ox 5.7 . 111.Sh AUTHORS 112.An Ted Unangst Aq Mt tedu@openbsd.org 113