Change the EVP_somecipher() and EVP_somedigest()

[openssl.git] / doc / crypto / EVP_DigestInit.pod

diff --git a/doc/crypto/EVP_DigestInit.pod b/doc/crypto/EVP_DigestInit.pod
index 345b1ddfa79c896875db6ab7d763c53a27cb20af..df17928b5df613863fab0163414db5d91c29ca26 100644 (file)
--- a/doc/crypto/EVP_DigestInit.pod
+++ b/doc/crypto/EVP_DigestInit.pod
@@ -2,15 +2,20 @@
 
 =head1 NAME
 
-EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines
+EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, EVP_MAX_MD_SIZE,
+EVP_MD_CTX_copy, EVP_MD_type, EVP_MD_pkey_type, EVP_MD_size, EVP_MD_block_size,
+EVP_MD_CTX_md, EVP_MD_CTX_size, EVP_MD_CTX_block_size, EVP_MD_CTX_type,
+EVP_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_dss, EVP_dss1, EVP_mdc2,
+EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj -
+EVP digest routines
 
 =head1 SYNOPSIS
 
  #include <openssl/evp.h>
 
- void EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
- void EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
- void EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
+ int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
+ int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt);
+ int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
         unsigned int *s);
 
  #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */
@@ -27,15 +32,15 @@ EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines
  #define EVP_MD_CTX_block_size(e)      EVP_MD_block_size((e)->digest)
  #define EVP_MD_CTX_type(e)            EVP_MD_type((e)->digest)
 
- EVP_MD *EVP_md_null(void);
- EVP_MD *EVP_md2(void);
- EVP_MD *EVP_md5(void);
- EVP_MD *EVP_sha(void);
- EVP_MD *EVP_sha1(void);
- EVP_MD *EVP_dss(void);
- EVP_MD *EVP_dss1(void);
- EVP_MD *EVP_mdc2(void);
- EVP_MD *EVP_ripemd160(void);
+ const EVP_MD *EVP_md_null(void);
+ const EVP_MD *EVP_md2(void);
+ const EVP_MD *EVP_md5(void);
+ const EVP_MD *EVP_sha(void);
+ const EVP_MD *EVP_sha1(void);
+ const EVP_MD *EVP_dss(void);
+ const EVP_MD *EVP_dss1(void);
+ const EVP_MD *EVP_mdc2(void);
+ const EVP_MD *EVP_ripemd160(void);
 
  const EVP_MD *EVP_get_digestbyname(const char *name);
  #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
@@ -45,12 +50,12 @@ EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal - EVP digest routines
 
 The EVP digest routines are a high level interface to message digests.
 
-EVP_DigestInit() initialises a digest context B<ctx> to use a digest
+EVP_DigestInit() initializes a digest context B<ctx> to use a digest
 B<type>: this will typically be supplied by a function such as
 EVP_sha1().
 
 EVP_DigestUpdate() hashes B<cnt> bytes of data at B<d> into the
-digest context B<ctx>. This funtion can be called several times on the
+digest context B<ctx>. This function can be called several times on the
 same B<ctx> to hash additional data.
 
 EVP_DigestFinal() retrieves the digest value from B<ctx> and places
@@ -58,7 +63,7 @@ it in B<md>. If the B<s> parameter is not NULL then the number of
 bytes of data written (i.e. the length of the digest) will be written
 to the integer at B<s>, at most B<EVP_MAX_MD_SIZE> bytes will be written.
 After calling EVP_DigestFinal() no additional calls to EVP_DigestUpdate()
-can be made, but EVP_DigestInit() can be called to initialiase a new
+can be made, but EVP_DigestInit() can be called to initialize a new
 digest operation.
 
 EVP_MD_CTX_copy() can be used to copy the message digest state from
@@ -97,12 +102,13 @@ returns is of zero length.
 
 EVP_get_digestbyname(), EVP_get_digestbynid() and EVP_get_digestbyobj()
 return an B<EVP_MD> structure when passed a digest name, a digest NID or
-an ASN1_OBJECT structure respectively. The digest table must be initialised
+an ASN1_OBJECT structure respectively. The digest table must be initialized
 using, for example, OpenSSL_add_all_digests() for these functions to work.
 
 =head1 RETURN VALUES
 
-EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() do not return values.
+EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal() return 1 for
+success and 0 for failure.
 
 EVP_MD_CTX_copy() returns 1 if successful or 0 for failure.
 
@@ -129,6 +135,10 @@ transparent to the digest used and much more flexible.
 SHA1 is the digest of choice for new applications. The other digest algorithms
 are still in common use.
 
+The functions EVP_DigestInit(), EVP_DigestUpdate() and EVP_DigestFinal(),
+did not return errors in OpenSSL versions before 0.9.7 or earlier. Software only
+versions of digest algorithms will never return error codes for these functions.
+
 =head1 EXAMPLE
 
 This example digests the data "Test Message\n" and "Hello World\n", using the
@@ -172,10 +182,6 @@ digest name passed on the command line.
 
 =head1 BUGS
 
-Several of the functions do not return values: maybe they should. Although the
-internal digest operations will never fail some future hardware based operations
-might.
-
 The link between digests and signing algorithms results in a situation where
 EVP_sha1() must be used with RSA and EVP_dss1() must be used with DSS
 even though they are identical digests.