From 3f2b5a88ad62c63caae1265f9055fb660c7eb407 Mon Sep 17 00:00:00 2001 From: "Dr. Stephen Henson" Date: Tue, 22 Feb 2000 14:16:23 +0000 Subject: [PATCH 1/1] Update docs. --- doc/crypto/EVP_DigestInit.pod | 10 ++--- doc/crypto/EVP_EncryptInit.pod | 78 +++++++++++++++++++++++++++++++++- 2 files changed, 81 insertions(+), 7 deletions(-) diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod index 2ab27c360c..9b62059063 100644 --- a/doc/crypto/EVP_DigestInit.pod +++ b/doc/crypto/EVP_DigestInit.pod @@ -96,7 +96,7 @@ returns is of zero length. EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return an B structure when passed a digest name, a digest NID or -and ASN1_OBJECT structure respectively. The digest table must be initialised +an ASN1_OBJECT structure respectively. The digest table must be initialised using, for example, OpenSSL_add_all_digests() for these functions to work. =head1 RETURN VALUES @@ -112,9 +112,9 @@ EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size(e), EVP_MD_size(), EVP_MD_CTX_block_size() and EVP_MD_block_size() return the digest or block size in bytes. -EVP_md_null(), EVP_MD *EVP_md2(), EVP_MD *EVP_md5(), EVP_MD *EVP_sha(), -EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return -pointers to the corresponding EVP_MD structures. +EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), +EVP_dss1(), EVP_mdc2() and EVP_ripemd160() return pointers to the +corresponding EVP_MD structures. EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj() return either an B structure or NULL if an error occurs. @@ -186,7 +186,7 @@ in code that must be recompiled if the size of B increases. L, L, L, L, L, L, -L +L, L =head1 HISTORY diff --git a/doc/crypto/EVP_EncryptInit.pod b/doc/crypto/EVP_EncryptInit.pod index 19dca2f612..c84f593dbb 100644 --- a/doc/crypto/EVP_EncryptInit.pod +++ b/doc/crypto/EVP_EncryptInit.pod @@ -29,7 +29,7 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines #define EVP_CIPHER_nid(e) ((e)->nid) #define EVP_CIPHER_block_size(e) ((e)->block_size) #define EVP_CIPHER_key_length(e) ((e)->key_len) - #define EVP_CIPHER_iv_length(e) ((e)->iv_len) + #define EVP_CIPHER_iv_length(e) ((e)->iv_len) int EVP_CIPHER_type(const EVP_CIPHER *ctx); #define EVP_CIPHER_CTX_cipher(e) ((e)->cipher) @@ -39,6 +39,9 @@ EVP_EncryptInit, EVP_EncryptUpdate, EVP_EncryptFinal - EVP cipher routines #define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len) #define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c)) + int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type); + =head1 DESCRIPTION The EVP cipher routines are a high level interface to certain @@ -48,7 +51,12 @@ EVP_EncryptInit() initialises a cipher context B for encryption with cipher B. B is normally supplied by a function such as EVP_des_cbc() . B is the symmetric key to use and B is the IV to use (if necessary), the actual number of bytes used for the -key and IV depends on the cipher. +key and IV depends on the cipher. It is possible to set all parameters +to NULL except B in an initial call and supply the remaining +parameters in subsequent calls. This is normally done when the +EVP_CIPHER_asn1_to_param() function is called to set the cipher +parameters from an ASN1 AlgorithmIdentifier and the key from a +different source. EVP_EncryptUpdate() encrypts B bytes from the buffer B and writes the encrypted version to B. This function can be called @@ -82,6 +90,56 @@ EVP_CIPHER_CTX_cleanup() clears all information from a cipher context. It should be called after all operations using a cipher are complete so sensitive information does not remain in memory. +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an EVP_CIPHER structure when passed a cipher name, a NID or an +ASN1_OBJECT structure. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return the NID of a cipher when +passed an B or B structure. The actual NID +value is an internal value which may not have a corresponding OBJECT +IDENTIFIER. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length of a cipher when passed an B or B +structure. The constant B is the maximum key length +for all ciphers. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length of a cipher when passed an B or B. +It will return zero if the cipher does not use an IV. The constant +B is the maximum IV length for all ciphers. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size of a cipher when passed an B or B +structure. The constant B is also the maximum block +length for all ciphers. + +EVP_CIPHER_type() and EVP_CIPHER_CTX_type() return the type of the passed +cipher or context. This "type" is the actual NID of the cipher OBJECT +IDENTIFIER as such it ignores the cipher parameters and 40 bit RC2 and +128 bit RC2 have the same NID. + +EVP_CIPHER_CTX_cipher() returns the B structure when passed +an B structure. + +EVP_CIPHER_param_to_asn1() sets the AlgorithmIdentifier "parameter" based +on the passed cipher. This will typically include any parameters and an +IV. The cipher IV (if any) must be set when this call is made. This call +should be made before the cipher is actually "used" (before any +EVP_EncryptUpdate(), EVP_DecryptUpdate() calls for example). This function +may fail if the cipher does not have any ASN1 support. + +EVP_CIPHER_asn1_to_param() sets the cipher parameters based on an ASN1 +AlgorithmIdentifier "parameter". The precise effect depends on the cipher +In the case of RC2, for example, it will set the IV and effective key length. +This function should be called after the base cipher type is set but before +the key is set. For example EVP_CipherInit() will be called with the IV and +key set to NULL, EVP_CIPHER_asn1_to_param() will be called and finally +EVP_CipherInit() again with all parameters except the key set to NULL. It is +possible for this function to fail if the cipher does not have any ASN1 support +or the parameters cannot be set (for example the RC2 effective key length +does not have an B structure). + =head1 RETURN VALUES EVP_EncryptInit(), EVP_EncryptUpdate() and EVP_EncryptFinal() do not return @@ -94,6 +152,22 @@ EVP_CipherInit() and EVP_CipherUpdate() do not return values. EVP_CipherFinal() returns 1 for a decryption failure or 1 for success, if the operation is encryption then it always returns 1. +EVP_CIPHER_CTX_cleanup() does not return a value. + +EVP_get_cipherbyname(), EVP_get_cipherbynid() and EVP_get_cipherbyobj() +return an B structure or NULL on error. + +EVP_CIPHER_nid() and EVP_CIPHER_CTX_nid() return a NID. + +EVP_CIPHER_block_size() and EVP_CIPHER_CTX_block_size() return the block +size. + +EVP_CIPHER_key_length() and EVP_CIPHER_CTX_key_length() return the key +length. + +EVP_CIPHER_iv_length() and EVP_CIPHER_CTX_iv_length() return the IV +length or zero if the cipher does not use an IV. + =head1 NOTES Where possible the B interface to symmetric ciphers should be used in -- 2.34.1