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 Original line Diff line number Diff line
@@ -67,7 +67,8 @@ EVP digest routines 




=head1 DESCRIPTION

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

EVP_MD_CTX_init() initializes digest context B<ctx>.

doc/crypto/EVP_EncryptInit.pod

+47 −31
Original line number Original line 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_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_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_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_128_cbc, EVP_aes_128_ecb, EVP_aes_128_cfb, EVP_aes_128_ofb,

EVP_aes_192_ccm, EVP_aes_256_ccm - EVP cipher routines

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

=head1 SYNOPSIS
@@ -291,70 +294,83 @@ All algorithms have a fixed key length unless otherwise stated. 




Null cipher: does nothing.

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.

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.

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.

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.

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.

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.

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.

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

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

length cipher with an additional parameter called "effective key bits" or "effective key length".

By default both are set to 128 bits.

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.

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

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.

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

Blowfish encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key

length cipher.

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

CAST encryption algorithm in CBC, ECB, CFB and OFB modes respectively. This is a variable key

length cipher.

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

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

cipher with an additional "number of rounds" parameter. By default the key length is set to 128

bits and 12 rounds.

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.

AES Galois Counter Mode (GCM) for 128, 192 and 256 bit keys respectively.

These ciphers require additional control operations to function correctly: see

These ciphers require additional control operations to function correctly: see

L<GCM mode> section below for details.

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.

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

These ciphers require additional control operations to function correctly: see

doc/crypto/blowfish.pod

+3 −7
Original line number Original line Diff line number Diff line
@@ -97,16 +97,12 @@ None of the functions presented here return any value. 
=head1 NOTE

=head1 NOTE





Applications should use the higher level functions

Applications should use the higher level functions

L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling the

L<EVP_EncryptInit(3)|EVP_EncryptInit(3)> etc. instead of calling these

blowfish functions directly.

functions directly.





=head1 SEE ALSO

=head1 SEE ALSO





L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>,

L<des_modes(7)|des_modes(7)>

L<des_modes(7)|des_modes(7)>





=head1 HISTORY



The Blowfish functions are available in all versions of SSLeay and OpenSSL.



=cut
 
=cut

doc/crypto/des.pod

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

default), DES_pcbc_encrypt is used.  If set to I<DES_CBC_MODE>

DES_cbc_encrypt is used.

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

=head1 BUGS





DES_3cbc_encrypt() is flawed and must not be used in applications.

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 B<des> library was written to be source code compatible with

the MIT Kerberos library.

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

=head1 HISTORY
@@ -354,4 +352,9 @@ MIT library. 
Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project

Eric Young (eay@cryptsoft.com). Modified for the OpenSSL project

(http://www.openssl.org).

(http://www.openssl.org).





=head1 SEE ALSO



L<des_modes(7)|des_modes(7)>,

L<EVP_EncryptInit(3)|EVP_EncryptInit(3)>



=cut
 
=cut

doc/crypto/md5.pod

+1 −10
Original line number Original line Diff line number Diff line
@@ -87,15 +87,6 @@ RFC 1319, RFC 1320, RFC 1321 




=head1 SEE ALSO

=head1 SEE ALSO





L<sha(3)|sha(3)>, L<ripemd(3)|ripemd(3)>, L<EVP_DigestInit(3)|EVP_DigestInit(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.





=cut
 
=cut