wbrawner/openssl
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

RT1665,2300: Crypto doc cleanups

Browse source 
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
Show stats Download patch file Download diff file Expand all files Collapse all files

3
doc/crypto/EVP_DigestInit.pod
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>.

50
doc/crypto/EVP_EncryptInit.pod
View file

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

10
doc/crypto/blowfish.pod
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

21
doc/crypto/des.pod
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

11
doc/crypto/md5.pod
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

7
doc/crypto/mdc2.pod
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

19
doc/crypto/rc4.pod
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

17
doc/crypto/ripemd.pod
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

7
doc/crypto/sha.pod
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