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>
This commit is contained in:
Rich Salz 2014-08-14 10:50:26 -04:00
parent ac53354b94
commit c7497f34fb
9 changed files with 83 additions and 90 deletions

View file

@ -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>.

View file

@ -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;

View file

@ -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

View file

@ -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
crypt(3), L<des_modes(7)|des_modes(7)>, L<evp(3)|evp(3)>, L<rand(3)|rand(3)>
Applications should use the higher level functions
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
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

View file

@ -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

View file

@ -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

View file

@ -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.
Applications should use the higher level functions
L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these
functions directly.
=head1 SEE ALSO
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

View file

@ -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

View file

@ -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