Commit c7497f34 authored by Rich Salz's avatar Rich Salz
Browse files

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: default avatarMatt Caswell <matt@openssl.org>
parent ac53354b

doc/crypto/EVP_DigestInit.pod

+2 −1
Original line number Diff line number Diff line
@@ -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>.

doc/crypto/EVP_EncryptInit.pod

+47 −31
Original line number Diff line number Diff line
@@ -25,8 +25,11 @@ 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_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
@@ -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()



AES with a 128-bit key in CBC, ECB, CFB and OFB modes respectively.



=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(void), EVP_des_ede(), EVP_des_ede_ofb(void),  EVP_des_ede_cfb(void)

=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

doc/crypto/blowfish.pod

+3 −7
Original line number Diff line number Diff line
@@ -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

doc/crypto/des.pod

+12 −9
Original line number Diff line number Diff line
@@ -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

doc/crypto/md5.pod

+1 −10
Original line number Diff line number Diff line
@@ -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