1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosPKCS5_PBKDF2_HMAC, PKCS5_PBKDF2_HMAC_SHA1 - password based derivation routines with salt and iteration count 6*4724848cSchristos 7*4724848cSchristos=head1 SYNOPSIS 8*4724848cSchristos 9*4724848cSchristos #include <openssl/evp.h> 10*4724848cSchristos 11*4724848cSchristos int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, 12*4724848cSchristos const unsigned char *salt, int saltlen, int iter, 13*4724848cSchristos const EVP_MD *digest, 14*4724848cSchristos int keylen, unsigned char *out); 15*4724848cSchristos 16*4724848cSchristos int PKCS5_PBKDF2_HMAC_SHA1(const char *pass, int passlen, 17*4724848cSchristos const unsigned char *salt, int saltlen, int iter, 18*4724848cSchristos int keylen, unsigned char *out); 19*4724848cSchristos 20*4724848cSchristos=head1 DESCRIPTION 21*4724848cSchristos 22*4724848cSchristosPKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count 23*4724848cSchristosas specified in RFC 2898. 24*4724848cSchristos 25*4724848cSchristosB<pass> is the password used in the derivation of length B<passlen>. B<pass> 26*4724848cSchristosis an optional parameter and can be NULL. If B<passlen> is -1, then the 27*4724848cSchristosfunction will calculate the length of B<pass> using strlen(). 28*4724848cSchristos 29*4724848cSchristosB<salt> is the salt used in the derivation of length B<saltlen>. If the 30*4724848cSchristosB<salt> is NULL, then B<saltlen> must be 0. The function will not 31*4724848cSchristosattempt to calculate the length of the B<salt> because it is not assumed to 32*4724848cSchristosbe NULL terminated. 33*4724848cSchristos 34*4724848cSchristosB<iter> is the iteration count and its value should be greater than or 35*4724848cSchristosequal to 1. RFC 2898 suggests an iteration count of at least 1000. Any 36*4724848cSchristosB<iter> less than 1 is treated as a single iteration. 37*4724848cSchristos 38*4724848cSchristosB<digest> is the message digest function used in the derivation. Values include 39*4724848cSchristosany of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls 40*4724848cSchristosPKCS5_PBKDF2_HMAC() with EVP_sha1(). 41*4724848cSchristos 42*4724848cSchristosThe derived key will be written to B<out>. The size of the B<out> buffer 43*4724848cSchristosis specified via B<keylen>. 44*4724848cSchristos 45*4724848cSchristos=head1 NOTES 46*4724848cSchristos 47*4724848cSchristosA typical application of this function is to derive keying material for an 48*4724848cSchristosencryption algorithm from a password in the B<pass>, a salt in B<salt>, 49*4724848cSchristosand an iteration count. 50*4724848cSchristos 51*4724848cSchristosIncreasing the B<iter> parameter slows down the algorithm which makes it 52*4724848cSchristosharder for an attacker to perform a brute force attack using a large number 53*4724848cSchristosof candidate passwords. 54*4724848cSchristos 55*4724848cSchristosThese functions make no assumption regarding the given password. 56*4724848cSchristosIt will simply be treated as a byte sequence. 57*4724848cSchristos 58*4724848cSchristos=head1 RETURN VALUES 59*4724848cSchristos 60*4724848cSchristosPKCS5_PBKDF2_HMAC() and PBKCS5_PBKDF2_HMAC_SHA1() return 1 on success or 0 on error. 61*4724848cSchristos 62*4724848cSchristos=head1 SEE ALSO 63*4724848cSchristos 64*4724848cSchristosL<evp(7)>, L<RAND_bytes(3)>, 65*4724848cSchristosL<EVP_BytesToKey(3)>, 66*4724848cSchristosL<passphrase-encoding(7)> 67*4724848cSchristos 68*4724848cSchristos=head1 COPYRIGHT 69*4724848cSchristos 70*4724848cSchristosCopyright 2014-2018 The OpenSSL Project Authors. All Rights Reserved. 71*4724848cSchristos 72*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 73*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 74*4724848cSchristosin the file LICENSE in the source distribution or at 75*4724848cSchristosL<https://www.openssl.org/source/license.html>. 76*4724848cSchristos 77*4724848cSchristos=cut 78