diff options
author | Dr. Stephen Henson <steve@openssl.org> | 2001-12-03 03:07:37 +0000 |
---|---|---|
committer | Dr. Stephen Henson <steve@openssl.org> | 2001-12-03 03:07:37 +0000 |
commit | 55e42c93a8336bd178718b3f82730f6de95710be (patch) | |
tree | ca0eddecfa85b149a55a8fe7fcc516b0269b8f04 /doc/crypto/EVP_BytesToKey.pod | |
parent | 6a0dec958428349875d91f89913dd0fda19b6584 (diff) |
EVP_BytesToKey documentation.
Diffstat (limited to 'doc/crypto/EVP_BytesToKey.pod')
-rw-r--r-- | doc/crypto/EVP_BytesToKey.pod | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/doc/crypto/EVP_BytesToKey.pod b/doc/crypto/EVP_BytesToKey.pod new file mode 100644 index 0000000000..5ce4add082 --- /dev/null +++ b/doc/crypto/EVP_BytesToKey.pod @@ -0,0 +1,67 @@ +=pod + +=head1 NAME + + EVP_BytesToKey - password based encryption routine + +=head1 SYNOPSIS + + #include <openssl/evp.h> + + int EVP_BytesToKey(const EVP_CIPHER *type,const EVP_MD *md, + const unsigned char *salt, + const unsigned char *data, int datal, int count, + unsigned char *key,unsigned char *iv); + +=head1 DESCRIPTION + +EVP_BytesToKey() derives a key and IV from various parameters. B<type> is +the cipher to derive the key and IV for. B<md> is the message digest to use. +The B<salt> paramter is used as a salt in the derivation: it should point to +an 8 byte buffer or NULL if no salt is used. B<data> is a buffer containing +B<datal> bytes which is used to derive the keying data. B<count> is the +iteration count to use. The derived key and IV will be written to B<key> +and B<iv> respectively. + +=head1 NOTES + +A typical application of this function is to derive keying material for an +encryption algorithm from a password in the B<data> parameter. + +Increasing the B<count> 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. + +If the total key and IV length is less than the digest length and +B<MD5> is used then the derivation algorithm is compatible with PKCS#5 v1.5 +otherwise a non standard extension is used to derive the extra data. + +Newer applications should use more standard algorithms such as PKCS#5 +v2.0 for key derivation. + +=head1 KEY DERIVATION ALGORITHM + +The key and IV is derived by concatenating D_1, D_2, etc until +enough data is available for the key and IV. D_i is defined as: + + D_i = HASH^count(D_(i-1) || data || salt) + +where || denotes concatentaion, D_0 is empty, HASH is the digest +algorithm in use, HASH^1(data) is simply HASH(data), HASH^2(data) +is HASH(HASH(data)) and so on. + +The initial bytes are used for the key and the subsequent bytes for +the IV. + +=head1 RETURN VALUES + +EVP_BytesToKey() returns the size of the derived key in bytes. + +=head1 SEE ALSO + +L<evp(3)|evp(3)>, L<rand(3)|rand(3)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, + +=head1 HISTORY + +=cut |