diff options
author | Rich Salz <rsalz@akamai.com> | 2014-08-14 10:50:26 -0400 |
---|---|---|
committer | Rich Salz <rsalz@akamai.com> | 2014-08-28 18:55:50 -0400 |
commit | c7497f34fbf3824dd4a0881d598e598980f2edb1 (patch) | |
tree | a27531ae0b3b39338c82e8db8575a5e6cda65abf | |
parent | ac53354b949a252610cf987dbc875a7717f295c4 (diff) |
RT1665,2300: Crypto doc cleanups
RT1665: aes documentation.
Paul Green wrote a nice aes.pod file.
But we now encourage the EVP interface.
So I took his RT item and used it as impetus to add
the AES modes to EVP_EncryptInit.pod
I also noticed that rc4.pod has spurious references to some other
cipher pages, so I removed them.
RT2300: Clean up MD history (merged into RT1665)
Put HISTORY section only in EVP_DigestInit.pod. Also add words
to discourage use of older cipher-specific API, and remove SEE ALSO
links that point to them.
Make sure digest pages have a NOTE that says use EVP_DigestInit.
Review feedback:
More cleanup in EVP_EncryptInit.pod
Fixed SEE ALSO links in ripemd160.pod, sha.pod, mdc2.pod, blowfish.pod,
rc4.d, and des.pod. Re-order sections in des.pod for consistency
Reviewed-by: Matt Caswell <matt@openssl.org>
-rw-r--r-- | doc/crypto/EVP_DigestInit.pod | 3 | ||||
-rw-r--r-- | doc/crypto/EVP_EncryptInit.pod | 78 | ||||
-rw-r--r-- | doc/crypto/blowfish.pod | 10 | ||||
-rw-r--r-- | doc/crypto/des.pod | 21 | ||||
-rw-r--r-- | doc/crypto/md5.pod | 11 | ||||
-rw-r--r-- | doc/crypto/mdc2.pod | 7 | ||||
-rw-r--r-- | doc/crypto/rc4.pod | 19 | ||||
-rw-r--r-- | doc/crypto/ripemd.pod | 17 | ||||
-rw-r--r-- | doc/crypto/sha.pod | 7 |
9 files changed, 83 insertions, 90 deletions
diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod index 0895e8c392..d9fada9c0b 100644 --- a/doc/crypto/EVP_DigestInit.pod +++ b/doc/crypto/EVP_DigestInit.pod @@ -67,7 +67,8 @@ EVP digest routines =head1 DESCRIPTION -The EVP digest routines are a high level interface to message digests. +The EVP digest routines are a high level interface to message digests, +and should be used instead of the cipher-specific functions. EVP_MD_CTX_init() initializes digest context B<ctx>. diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index 57b3458269..d68d4bca5b 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -24,9 +24,12 @@ EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc, EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, -EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, -EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, -EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines +EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, +EVP_aes_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb, +EVP_aes_192_cbc, EVP_aes_192_ecb, EVP_aes_192_cfb, EVP_aes_192_ofb, +EVP_aes_256_cbc, EVP_aes_256_ecb, EVP_aes_256_cfb, EVP_aes_256_ofb, +EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, +EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines =head1 SYNOPSIS @@ -138,7 +141,7 @@ calls to EVP_EncryptUpdate() should be made. If padding is disabled then EVP_EncryptFinal_ex() will not encrypt any more data and it will return an error if any data remains in a partial block: -that is if the total data length is not a multiple of the block size. +that is if the total data length is not a multiple of the block size. EVP_DecryptInit_ex(), EVP_DecryptUpdate() and EVP_DecryptFinal_ex() are the corresponding decryption operations. EVP_DecryptFinal() will return an @@ -278,7 +281,7 @@ OBJECT IDENTIFIER or NID_undef if it has no defined OBJECT IDENTIFIER. EVP_CIPHER_CTX_cipher() returns an B<EVP_CIPHER> structure. -EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for +EVP_CIPHER_param_to_asn1() and EVP_CIPHER_asn1_to_param() return 1 for success or zero for failure. =head1 CIPHER LISTING @@ -291,70 +294,83 @@ All algorithms have a fixed key length unless otherwise stated. Null cipher: does nothing. -=item EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void) +=item EVP_aes_128_cbc(), EVP_aes_128_ecb(), EVP_aes_128_cfb(), EVP_aes_128_ofb() -DES in CBC, ECB, CFB and OFB modes respectively. +AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void) +=item EVP_aes_192_cbc(), EVP_aes_192_ecb(), EVP_aes_192_cfb(), EVP_aes_192_ofb() + +AES with a 192-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_aes_256_cbc(), EVP_aes_256_ecb(), EVP_aes_256_cfb(), EVP_aes_256_ofb() + +AES with a 256-bit key in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_cbc(), EVP_des_ecb(), EVP_des_cfb(), EVP_des_ofb() + +DES in CBC, ECB, CFB and OFB modes respectively. + +=item EVP_des_ede_cbc(), EVP_des_ede(), EVP_des_ede_ofb(), EVP_des_ede_cfb() Two key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void) +=item EVP_des_ede3_cbc(), EVP_des_ede3(), EVP_des_ede3_ofb(), EVP_des_ede3_cfb() Three key triple DES in CBC, ECB, CFB and OFB modes respectively. -=item EVP_desx_cbc(void) +=item EVP_desx_cbc() DESX algorithm in CBC mode. -=item EVP_rc4(void) +=item EVP_rc4() RC4 stream cipher. This is a variable key length cipher with default key length 128 bits. -=item EVP_rc4_40(void) +=item EVP_rc4_40() -RC4 stream cipher with 40 bit key length. This is obsolete and new code should use EVP_rc4() +RC4 stream cipher with 40 bit key length. +This is obsolete and new code should use EVP_rc4() and the EVP_CIPHER_CTX_set_key_length() function. -=item EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void) +=item EVP_idea_cbc() EVP_idea_ecb(), EVP_idea_cfb(), EVP_idea_ofb(), EVP_idea_cbc() IDEA encryption algorithm in CBC, ECB, CFB and OFB modes respectively. -=item EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void) +=item EVP_rc2_cbc(), EVP_rc2_ecb(), EVP_rc2_cfb(), EVP_rc2_ofb() RC2 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional parameter called "effective key bits" or "effective key length". By default both are set to 128 bits. -=item EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void) +=item EVP_rc2_40_cbc(), EVP_rc2_64_cbc() RC2 algorithm in CBC mode with a default key length and effective key length of 40 and 64 bits. These are obsolete and new code should use EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() and EVP_CIPHER_CTX_ctrl() to set the key length and effective key length. -=item EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void); +=item EVP_bf_cbc(), EVP_bf_ecb(), EVP_bf_cfb(), EVP_bf_ofb() Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void) +=item EVP_cast5_cbc(), EVP_cast5_ecb(), EVP_cast5_cfb(), EVP_cast5_ofb() CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher. -=item EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void) +=item EVP_rc5_32_12_16_cbc(), EVP_rc5_32_12_16_ecb(), EVP_rc5_32_12_16_cfb(), EVP_rc5_32_12_16_ofb() RC5 encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key length cipher with an additional "number of rounds" parameter. By default the key length is set to 128 bits and 12 rounds. -=item EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void) +=item EVP_aes_128_gcm(), EVP_aes_192_gcm(), EVP_aes_256_gcm() AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see L<GCM mode> section below for details. -=item EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void) +=item EVP_aes_128_ccm(), EVP_aes_192_ccm(), EVP_aes_256_ccm() AES Counter with CBC-MAC Mode (CCM) for 128, 192 and 256 bit keys respectively. These ciphers require additional control operations to function correctly: see @@ -368,7 +384,7 @@ For GCM mode ciphers the behaviour of the EVP interface is subtly altered and several GCM specific ctrl operations are supported. To specify any additional authenticated data (AAD) a call to EVP_CipherUpdate(), -EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output +EVP_EncryptUpdate() or EVP_DecryptUpdate() should be made with the output parameter B<out> set to B<NULL>. When decrypting the return value of EVP_DecryptFinal() or EVP_CipherFinal() @@ -382,7 +398,7 @@ The following ctrls are supported in GCM mode: Sets the GCM IV length: this call can only be made before specifying an IV. If not called a default IV length is used (96 bits for AES). - + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag); Writes B<taglen> bytes of the tag value to the buffer indicated by B<tag>. @@ -393,7 +409,7 @@ processed (e.g. after an EVP_EncryptFinal() call). Sets the expected tag to B<taglen> bytes from B<tag>. This call is only legal when decrypting data and must be made B<before> any data is processed (e.g. -before any EVP_DecryptUpdate() call). +before any EVP_DecryptUpdate() call). See L<EXAMPLES> below for an example of the use of GCM mode. @@ -403,14 +419,14 @@ The behaviour of CCM mode ciphers is similar to CCM mode but with a few additional requirements and different ctrl values. Like GCM mode any additional authenticated data (AAD) is passed by calling -EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output +EVP_CipherUpdate(), EVP_EncryptUpdate() or EVP_DecryptUpdate() with the output parameter B<out> set to B<NULL>. Additionally the total plaintext or ciphertext length B<MUST> be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or -EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) +EVP_DecryptUpdate() with the output and input parameters (B<in> and B<out>) set to B<NULL> and the length passed in the B<inl> parameter. The following ctrls are supported in CCM mode: - + EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag); This call is made to set the expected B<CCM> tag value when decrypting or @@ -439,7 +455,7 @@ B<EVP> interface will ensure the use of platform specific cryptographic acceleration such as AES-NI (the low level interfaces do not provide the guarantee). -PKCS padding works by adding B<n> padding bytes of value B<n> to make the total +PKCS padding works by adding B<n> padding bytes of value B<n> to make the total length of the encrypted data a multiple of the block size. Padding is always added so if the data is already a multiple of the block size B<n> will equal the block size. For example if the block size is 8 and 11 bytes are to be @@ -469,7 +485,7 @@ a limitation of the current RC5 code rather than the EVP interface. EVP_MAX_KEY_LENGTH and EVP_MAX_IV_LENGTH only refer to the internal ciphers with default key lengths. If custom ciphers exceed these values the results are -unpredictable. This is because it has become standard practice to define a +unpredictable. This is because it has become standard practice to define a generic key as a fixed unsigned char array containing EVP_MAX_KEY_LENGTH bytes. The ASN1 code is incomplete (and sometimes inaccurate) it has only been tested @@ -523,7 +539,7 @@ Encrypt a string using IDEA: The ciphertext from the above example can be decrypted using the B<openssl> utility with the command line (shown on two lines for clarity): - + openssl idea -d <filename -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708 @@ -552,7 +568,7 @@ with a 128-bit key: /* Now we can set key and IV */ EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt); - for(;;) + for(;;) { inlen = fread(inbuf, 1, 1024, in); if(inlen <= 0) break; diff --git a/doc/crypto/blowfish.pod b/doc/crypto/blowfish.pod index 5b2d274c15..31438ab73a 100644 --- a/doc/crypto/blowfish.pod +++ b/doc/crypto/blowfish.pod @@ -97,16 +97,12 @@ None of the functions presented here return any value. =head1 NOTE Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the -blowfish functions directly. +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these +functions directly. =head1 SEE ALSO +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>, L<des_modes(7)|des_modes(7)> -=head1 HISTORY - -The Blowfish functions are available in all versions of SSLeay and OpenSSL. - =cut - diff --git a/doc/crypto/des.pod b/doc/crypto/des.pod index e1add56b5e..51df21a4f9 100644 --- a/doc/crypto/des.pod +++ b/doc/crypto/des.pod @@ -279,13 +279,6 @@ DES_enc_read() and DES_end_write(). If set to I<DES_PCBC_MODE> (the default), DES_pcbc_encrypt is used. If set to I<DES_CBC_MODE> DES_cbc_encrypt is used. -=head1 NOTES - -Single-key DES is insecure due to its short key size. ECB mode is -not suitable for most applications; see L<des_modes(7)|des_modes(7)>. - -The L<evp(3)|evp(3)> library provides higher-level encryption functions. - =head1 BUGS DES_3cbc_encrypt() is flawed and must not be used in applications. @@ -314,9 +307,14 @@ ANSI X3.106 The B<des> library was written to be source code compatible with the MIT Kerberos library. -=head1 SEE ALSO +=head1 NOTES + +Applications should use the higher level functions +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these +functions directly. -crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)> +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see L<des_modes(7)|des_modes(7)>. =head1 HISTORY @@ -354,4 +352,9 @@ MIT library. Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project (http://www.openssl.org). +=head1 SEE ALSO + +L<des_modes(7)|des_modes(7)>, +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> + =cut diff --git a/doc/crypto/md5.pod b/doc/crypto/md5.pod index d11d5c32cb..41a547898a 100644 --- a/doc/crypto/md5.pod +++ b/doc/crypto/md5.pod @@ -87,15 +87,6 @@ RFC 1319, RFC 1320, RFC 1321 =head1 SEE ALSO -L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MD2(), MD2_Init(), MD2_Update() MD2_Final(), MD5(), MD5_Init(), -MD5_Update() and MD5_Final() are available in all versions of SSLeay -and OpenSSL. - -MD4(), MD4_Init(), and MD4_Update() are available in OpenSSL 0.9.6 and -above. +L<EVP_DigestInit(3)|EVP_DigestInit(3)> =cut diff --git a/doc/crypto/mdc2.pod b/doc/crypto/mdc2.pod index 41f648af36..2795868073 100644 --- a/doc/crypto/mdc2.pod +++ b/doc/crypto/mdc2.pod @@ -54,11 +54,6 @@ ISO/IEC 10118-2, with DES =head1 SEE ALSO -L<sha(3)|sha(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since -SSLeay 0.8. +L<EVP_DigestInit(3)|EVP_DigestInit(3)> =cut diff --git a/doc/crypto/rc4.pod b/doc/crypto/rc4.pod index b6d3a4342c..bbf0f27f47 100644 --- a/doc/crypto/rc4.pod +++ b/doc/crypto/rc4.pod @@ -37,26 +37,25 @@ Since RC4 is a stream cipher (the input is XORed with a pseudo-random key stream to produce the output), decryption uses the same function calls as encryption. -Applications should use the higher level functions -L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> -etc. instead of calling the RC4 functions directly. - =head1 RETURN VALUES RC4_set_key() and RC4() do not return values. =head1 NOTE -Certain conditions have to be observed to securely use stream ciphers. -It is not permissible to perform multiple encryptions using the same -key stream. - -=head1 SEE ALSO +Applications should use the higher level functions +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these +functions directly. -L<blowfish(3)|blowfish(3)>, L<des(3)|des(3)>, L<rc2(3)|rc2(3)> +It is difficult to securely use stream ciphers. For example, do not perform +multiple encryptions using the same key stream. =head1 HISTORY RC4_set_key() and RC4() are available in all versions of SSLeay and OpenSSL. +=head1 SEE ALSO + +L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> + =cut diff --git a/doc/crypto/ripemd.pod b/doc/crypto/ripemd.pod index 264bb99ae7..e5ca3ad8d3 100644 --- a/doc/crypto/ripemd.pod +++ b/doc/crypto/ripemd.pod @@ -39,10 +39,6 @@ RIPEMD160_Final() places the message digest in B<md>, which must have space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases the B<RIPEMD160_CTX>. -Applications should use the higher level functions -L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling the -hash functions directly. - =head1 RETURN VALUES RIPEMD160() returns a pointer to the hash value. @@ -50,17 +46,18 @@ RIPEMD160() returns a pointer to the hash value. RIPEMD160_Init(), RIPEMD160_Update() and RIPEMD160_Final() return 1 for success, 0 otherwise. +=head1 NOTE + +Applications should use the higher level functions +L<EVP_DigestInit(3)|EVP_DigestInit(3)> etc. instead of calling these +functions directly. + =head1 CONFORMING TO ISO/IEC 10118-3 (draft) (??) =head1 SEE ALSO -L<sha(3)|sha(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. +L<EVP_DigestInit(3)|EVP_DigestInit(3)> =cut diff --git a/doc/crypto/sha.pod b/doc/crypto/sha.pod index 94ab7bc724..4c1ab71022 100644 --- a/doc/crypto/sha.pod +++ b/doc/crypto/sha.pod @@ -60,11 +60,6 @@ ANSI X9.30 =head1 SEE ALSO -L<ripemd(3)|ripemd(3)>, L<hmac(3)|hmac(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(3)> - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. +L<EVP_DigestInit(3)|EVP_DigestInit(3)> =cut |