From c7497f34fbf3824dd4a0881d598e598980f2edb1 Mon Sep 17 00:00:00 2001 From: Rich Salz Date: Thu, 14 Aug 2014 10:50:26 -0400 Subject: [PATCH] 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 --- doc/crypto/EVP_DigestInit.pod | 3 +- doc/crypto/EVP_EncryptInit.pod | 78 ++++++++++++++++++++-------------- doc/crypto/blowfish.pod | 10 ++--- doc/crypto/des.pod | 21 +++++---- doc/crypto/md5.pod | 11 +---- doc/crypto/mdc2.pod | 7 +-- doc/crypto/rc4.pod | 19 ++++----- doc/crypto/ripemd.pod | 17 +++----- 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. 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 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 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 set to B. 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 bytes of the tag value to the buffer indicated by B. @@ -393,7 +409,7 @@ processed (e.g. after an EVP_EncryptFinal() call). Sets the expected tag to B bytes from B. This call is only legal when decrypting data and must be made B any data is processed (e.g. -before any EVP_DecryptUpdate() call). +before any EVP_DecryptUpdate() call). See L 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 set to B. Additionally the total plaintext or ciphertext length B be passed to EVP_CipherUpdate(), EVP_EncryptUpdate() or -EVP_DecryptUpdate() with the output and input parameters (B and B) +EVP_DecryptUpdate() with the output and input parameters (B and B) set to B and the length passed in the B 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 tag value when decrypting or @@ -439,7 +455,7 @@ B 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 padding bytes of value B to make the total +PKCS padding works by adding B padding bytes of value B 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 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 utility with the command line (shown on two lines for clarity): - + openssl idea -d etc. instead of calling the -blowfish functions directly. +L etc. instead of calling these +functions directly. =head1 SEE ALSO +L, L -=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 (the default), DES_pcbc_encrypt is used. If set to I 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. - -The L 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 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 etc. instead of calling these +functions directly. -crypt(3), L, L, L +Single-key DES is insecure due to its short key size. ECB mode is +not suitable for most applications; see L. =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, +L + =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, L, L - -=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 =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, L - -=head1 HISTORY - -MDC2(), MDC2_Init(), MDC2_Update() and MDC2_Final() are available since -SSLeay 0.8. +L =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 -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 etc. instead of calling these +functions directly. -L, L, L +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 + =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, which must have space for RIPEMD160_DIGEST_LENGTH == 20 bytes of output, and erases the B. -Applications should use the higher level functions -L 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 etc. instead of calling these +functions directly. + =head1 CONFORMING TO ISO/IEC 10118-3 (draft) (??) =head1 SEE ALSO -L, L, L - -=head1 HISTORY - -RIPEMD160(), RIPEMD160_Init(), RIPEMD160_Update() and -RIPEMD160_Final() are available since SSLeay 0.9.0. +L =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, L, L - -=head1 HISTORY - -SHA1(), SHA1_Init(), SHA1_Update() and SHA1_Final() are available in all -versions of SSLeay and OpenSSL. +L =cut -- 2.34.1