diff options
author | Matt Caswell <frodo@baggins.org> | 2014-04-26 21:44:26 +0100 |
---|---|---|
committer | Matt Caswell <frodo@baggins.org> | 2014-04-26 21:44:26 +0100 |
commit | 6bcc4475fcdb2ea5daae80cbb2a5a5fcf677ac23 (patch) | |
tree | 34b44c896691024b7ed8d5068a7b372a69e06cfd /doc/crypto | |
parent | 8acb953880bc7fc5ed4e339de06dff0a213fa274 (diff) |
PKCS5_PBKDF2_HMAC documentation submitted by Jeffrey Walton
Diffstat (limited to 'doc/crypto')
-rw-r--r-- | doc/crypto/EVP_BytesToKey.pod | 1 | ||||
-rw-r--r-- | doc/crypto/PKCS5_PBKDF2_HMAC.pod | 62 |
2 files changed, 63 insertions, 0 deletions
diff --git a/doc/crypto/EVP_BytesToKey.pod b/doc/crypto/EVP_BytesToKey.pod index cd09b68ca8..d07ae6c7b5 100644 --- a/doc/crypto/EVP_BytesToKey.pod +++ b/doc/crypto/EVP_BytesToKey.pod @@ -60,6 +60,7 @@ EVP_BytesToKey() returns the size of the derived key in bytes, or 0 on error. =head1 SEE ALSO L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, +L<PKCS5_PBKDF2_HMAC(3)|PKCS5_PBKDF2_HMAC(3)>, L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> =head1 HISTORY diff --git a/doc/crypto/PKCS5_PBKDF2_HMAC.pod b/doc/crypto/PKCS5_PBKDF2_HMAC.pod new file mode 100644 index 0000000000..f8914db3e2 --- /dev/null +++ b/doc/crypto/PKCS5_PBKDF2_HMAC.pod @@ -0,0 +1,62 @@ +=pod + +=head1 NAME + +PKCS5_PBKDF2_HMAC - password based derivation routine with salt and iteration count + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int PKCS5_PBKDF2_HMAC(const char *pass, int passlen, + const unsigned char *salt, int saltlen, int iter, + const EVP_MD *digest, + int keylen, unsigned char *out); + +=head1 DESCRIPTION + +PKCS5_PBKDF2_HMAC() derives a key from a password using a salt and iteration count +as specified in RFC 2898. + +B<pass> is the password used in the derivation of length B<passlen>. B<pass> +is an optional parameter and can be NULL. If B<passlen> is -1, then the +function will calculate the length of B<pass> using strlen(). + +B<salt> is the salt used in the derivation of length B<saltlen>. If the +B<salt> is NULL, then B<saltlen> must be 0. The function will not +attempt to calculate the length of the B<salt> because its not assumed to +be NULL terminated. + +B<iter> is the iteration count and its value should be greater than or +equal to 1. RFC 2898 suggests an iteration count of at least 1000. Any +B<iter> less than 1 is treated as a single iteration. + +B<digest> is message digest function used in the derivation. Values include +any of the EVP_* message digests. PKCS5_PBKDF2_HMAC_SHA1() calls +PKCS5_PBKDF2_HMAC() with EVP_sha1(). + +The derived key will be written to B<out>. The size of the B<out> buffer +is specified via B<keylen>. + +=head1 NOTES + +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the B<pass>, a salt in B<salt>, +and an iteration count. + +Increasing the B<iter> parameter slows down the algorithm which makes it +harder for an attacker to peform a brute force attack using a large number +of candidate passwords. + +=head1 RETURN VALUES + +PKCS5_PBKDF2_HMAC() returns 1 on success or 0 on error. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, +L<EVP_BytesToKey(3)|EVP_BytesToKey(3)> + +=head1 HISTORY + +=cut |