jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: bcrypt_pbkdf.3,v 1.7 2025/06/06 22:01:39 schwarze Exp $
2.\"
3.\" Copyright (c) 2012 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: June 6 2025 $
18.Dt BCRYPT_PBKDF 3
19.Os
20.Sh NAME
21.Nm bcrypt_pbkdf
22.Nd bcrypt password-based key derivation function
23.Sh SYNOPSIS
24.Lb libutil
25.In util.h
26.Ft int
27.Fn bcrypt_pbkdf "const char *pass" "size_t pass_len" "const uint8_t *salt" \
28 "size_t salt_len" "uint8_t *key" "size_t key_len" "unsigned int rounds"
29.Sh DESCRIPTION
30The
31.Nm
32function converts a password into a byte array suitable for use as
33an encryption key.
34The password and salt values are combined and repeatedly hashed
35.Ar rounds
36times.
37The salt value should be randomly generated beforehand.
38The repeated hashing is designed to thwart discovery of the key via
39password guessing attacks.
40The higher the number of rounds, the slower each attempt will be.
41.\" A minimum value of at least 4 is recommended.
42.Sh RETURN VALUES
43The
44.Fn bcrypt_pbkdf
45function returns 0 to indicate success and \-1 for failure.
46.\" .Sh EXAMPLES
47.\" .Sh ERRORS
48.Sh SEE ALSO
49.Xr bcrypt 3
50.Sh STANDARDS
51.Rs
52.%A Niels Provos and David Mazieres
53.%D June 1999
54.%T A Future-Adaptable Password Scheme
55.Re
56.Pp
57.Rs
58.%A B. Kaliski
59.%D September 2000
60.%R RFC 2898
61.%T PKCS #5: Password-Based Cryptography Specification Version 2.0
62.Re
63.\" .Sh HISTORY
64.\" .Sh AUTHORS
65.Sh CAVEATS
66This implementation deviates slightly from the PBKDF2 standard by mixing
67output key bits nonlinearly.
68By mixing the output bytes together, an attacker is required to perform
69all of the work without taking any shortcuts.
70.\" .Sh BUGS