1.\" $OpenBSD: crypt_checkpass.3,v 1.13 2021/10/29 10:54:33 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: October 29 2021 $ 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 pwd.h 26.In unistd.h 27.Ft int 28.Fn crypt_checkpass "const char *password" "const char *hash" 29.Ft int 30.Fn crypt_newhash "const char *password" "const char *pref" "char *hash" "size_t hashsize" 31.Sh DESCRIPTION 32The 33.Fn crypt_checkpass 34function simplifies checking a user's password. 35If both the 36.Fa hash 37and the 38.Fa password 39are the empty string, authentication 40is a success. 41Otherwise, the 42.Fa password 43is hashed and compared to the provided 44.Fa hash . 45If the 46.Fa hash 47is 48.Dv NULL , 49authentication will always fail, but a default 50amount of work is performed to simulate the hashing operation. 51A successful match will return 0. 52A failure will return \-1 and set 53.Xr errno 2 . 54.Pp 55The 56.Fn crypt_newhash 57function simplifies the creation of new password hashes. 58The provided 59.Fa password 60is randomly salted and hashed and stored in 61.Fa hash . 62The size of the available space is specified by 63.Fa hashsize , 64which should be 65.Dv _PASSWORD_LEN . 66The 67.Fa pref 68argument identifies the preferred hashing algorithm and parameters. 69Possible values are: 70.Bl -tag -width Ds 71.It Dq bcrypt,<rounds> 72The bcrypt algorithm, where the value of rounds can be between 4 and 31 and 73specifies the base 2 logarithm of the number of rounds. 74If rounds is omitted or the special value 75.Sq a , 76an appropriate number of rounds is automatically selected based on system 77performance. 78.El 79.Sh RETURN VALUES 80.Rv -std crypt_checkpass crypt_newhash 81.Sh ERRORS 82The 83.Fn crypt_checkpass 84function sets 85.Va errno 86to 87.Er EACCES 88when authentication fails. 89.Pp 90The 91.Fn crypt_newhash 92function sets 93.Va errno 94to 95.Er EINVAL 96if 97.Fa pref 98is unsupported or insufficient space is provided. 99.Sh SEE ALSO 100.Xr crypt 3 , 101.Xr login.conf 5 , 102.Xr passwd 5 103.Sh HISTORY 104The function 105.Fn crypt_checkpass 106first appeared in 107.Ox 5.6 , 108and 109.Fn crypt_newhash 110in 111.Ox 5.7 . 112.Sh AUTHORS 113.An Ted Unangst Aq Mt tedu@openbsd.org 114