diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EVP_DigestInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/EVP_DigestInit.3 | 133 |
1 files changed, 95 insertions, 38 deletions
diff --git a/secure/lib/libcrypto/man/EVP_DigestInit.3 b/secure/lib/libcrypto/man/EVP_DigestInit.3 index e521c2e..ec683f0 100644 --- a/secure/lib/libcrypto/man/EVP_DigestInit.3 +++ b/secure/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,5 +1,5 @@ .\" Automatically generated by Pod::Man version 1.15 -.\" Tue Jul 30 09:21:40 2002 +.\" Mon Jan 13 19:28:02 2003 .\" .\" Standard preamble: .\" ====================================================================== @@ -138,12 +138,13 @@ .\" ====================================================================== .\" .IX Title "EVP_DigestInit 3" -.TH EVP_DigestInit 3 "0.9.6e" "2002-07-30" "OpenSSL" +.TH EVP_DigestInit 3 "0.9.7" "2003-01-13" "OpenSSL" .UC .SH "NAME" -EVP_DigestInit, EVP_DigestUpdate, EVP_DigestFinal, \s-1EVP_MAX_MD_SIZE\s0, -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_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, +EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, \s-1EVP_MAX_MD_SIZE\s0, +EVP_MD_CTX_copy_ex 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 \- \&\s-1EVP\s0 digest routines @@ -152,18 +153,34 @@ EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj \- .Vb 1 \& #include <openssl/evp.h> .Ve +.Vb 2 +\& void EVP_MD_CTX_init(EVP_MD_CTX *ctx); +\& EVP_MD_CTX *EVP_MD_CTX_create(void); +.Ve .Vb 4 -\& 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_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl); +\& int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, unsigned int cnt); +\& int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md, \& unsigned int *s); .Ve +.Vb 2 +\& int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx); +\& void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx); +.Ve .Vb 1 -\& #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ +\& int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in); +.Ve +.Vb 3 +\& int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type); +\& int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md, +\& unsigned int *s); .Ve .Vb 1 \& int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); .Ve +.Vb 1 +\& #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ +.Ve .Vb 4 \& #define EVP_MD_type(e) ((e)->type) \& #define EVP_MD_pkey_type(e) ((e)->pkey_type) @@ -177,15 +194,15 @@ EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj \- \& #define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest) .Ve .Vb 9 -\& 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); .Ve .Vb 3 \& const EVP_MD *EVP_get_digestbyname(const char *name); @@ -196,25 +213,48 @@ EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj \- .IX Header "DESCRIPTION" The \s-1EVP\s0 digest routines are a high level interface to message digests. .PP -\&\fIEVP_DigestInit()\fR initializes a digest context \fBctx\fR to use a digest -\&\fBtype\fR: this will typically be supplied by a function such as -\&\fIEVP_sha1()\fR. +\&\fIEVP_MD_CTX_init()\fR initializes digest contet \fBctx\fR. +.PP +\&\fIEVP_MD_CTX_create()\fR allocates, initializes and returns a digest contet. +.PP +\&\fIEVP_DigestInit_ex()\fR sets up digest context \fBctx\fR to use a digest +\&\fBtype\fR from \s-1ENGINE\s0 \fBimpl\fR. \fBctx\fR must be initialized before calling this +function. \fBtype\fR will typically be supplied by a functionsuch as \fIEVP_sha1()\fR. +If \fBimpl\fR is \s-1NULL\s0 then the default implementation of digest \fBtype\fR is used. .PP \&\fIEVP_DigestUpdate()\fR hashes \fBcnt\fR bytes of data at \fBd\fR into the digest context \fBctx\fR. This function can be called several times on the same \fBctx\fR to hash additional data. .PP -\&\fIEVP_DigestFinal()\fR retrieves the digest value from \fBctx\fR and places +\&\fIEVP_DigestFinal_ex()\fR retrieves the digest value from \fBctx\fR and places it in \fBmd\fR. If the \fBs\fR parameter is not \s-1NULL\s0 then the number of bytes of data written (i.e. the length of the digest) will be written to the integer at \fBs\fR, at most \fB\s-1EVP_MAX_MD_SIZE\s0\fR bytes will be written. -After calling \fIEVP_DigestFinal()\fR no additional calls to \fIEVP_DigestUpdate()\fR -can be made, but \fIEVP_DigestInit()\fR can be called to initialize a new +After calling \fIEVP_DigestFinal_ex()\fR no additional calls to \fIEVP_DigestUpdate()\fR +can be made, but \fIEVP_DigestInit_ex()\fR can be called to initialize a new digest operation. .PP -\&\fIEVP_MD_CTX_copy()\fR can be used to copy the message digest state from +\&\fIEVP_MD_CTX_cleanup()\fR cleans up digest context \fBctx\fR, it should be called +after a digest context is no longer needed. +.PP +\&\fIEVP_MD_CTX_destroy()\fR cleans up digest context \fBctx\fR and frees up the +space allocated to it, it should be called only on a context created +using \fIEVP_MD_CTX_create()\fR. +.PP +\&\fIEVP_MD_CTX_copy_ex()\fR can be used to copy the message digest state from \&\fBin\fR to \fBout\fR. This is useful if large amounts of data are to be -hashed which only differ in the last few bytes. +hashed which only differ in the last few bytes. \fBout\fR must be initialized +before calling this function. +.PP +\&\fIEVP_DigestInit()\fR behaves in the same way as \fIEVP_DigestInit_ex()\fR except +the passed context \fBctx\fR does not have to be initialized, and it always +uses the default digest implementation. +.PP +\&\fIEVP_DigestFinal()\fR is similar to \fIEVP_DigestFinal_ex()\fR except the digest +contet \fBctx\fR is automatically cleaned up. +.PP +\&\fIEVP_MD_CTX_copy()\fR is similar to \fIEVP_MD_CTX_copy_ex()\fR except the destination +\&\fBout\fR does not have to be initialized. .PP \&\fIEVP_MD_size()\fR and \fIEVP_MD_CTX_size()\fR return the size of the message digest when passed an \fB\s-1EVP_MD\s0\fR or an \fB\s-1EVP_MD_CTX\s0\fR structure, i.e. the size of the @@ -252,9 +292,10 @@ an \s-1ASN1_OBJECT\s0 structure respectively. The digest table must be initializ using, for example, \fIOpenSSL_add_all_digests()\fR for these functions to work. .SH "RETURN VALUES" .IX Header "RETURN VALUES" -\&\fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR and \fIEVP_DigestFinal()\fR do not return values. +\&\fIEVP_DigestInit_ex()\fR, \fIEVP_DigestUpdate()\fR and \fIEVP_DigestFinal_ex()\fR return 1 for +success and 0 for failure. .PP -\&\fIEVP_MD_CTX_copy()\fR returns 1 if successful or 0 for failure. +\&\fIEVP_MD_CTX_copy_ex()\fR returns 1 if successful or 0 for failure. .PP \&\fIEVP_MD_type()\fR, \fIEVP_MD_pkey_type()\fR and \fIEVP_MD_type()\fR return the \s-1NID\s0 of the corresponding \s-1OBJECT\s0 \s-1IDENTIFIER\s0 or NID_undef if none exists. @@ -277,6 +318,19 @@ transparent to the digest used and much more flexible. .PP \&\s-1SHA1\s0 is the digest of choice for new applications. The other digest algorithms are still in common use. +.PP +For most applications the \fBimpl\fR parameter to \fIEVP_DigestInit_ex()\fR will be +set to \s-1NULL\s0 to use the default digest implementation. +.PP +The functions \fIEVP_DigestInit()\fR, \fIEVP_DigestFinal()\fR and \fIEVP_MD_CTX_copy()\fR are +obsolete but are retained to maintain compatibility with existing code. New +applications should use \fIEVP_DigestInit_ex()\fR, \fIEVP_DigestFinal_ex()\fR and +\&\fIEVP_MD_CTX_copy_ex()\fR because they can efficiently reuse a digest context +instead of initializing and cleaning it up on each call and allow non default +implementations of digests to be specified. +.PP +In OpenSSL 0.9.7 and later if digest contexts are not cleaned up after use +memory leaks will occur. .SH "EXAMPLE" .IX Header "EXAMPLE" This example digests the data \*(L"Test Message\en\*(R" and \*(L"Hello World\en\*(R", using the @@ -314,11 +368,13 @@ digest name passed on the command line. \& exit(1); \& } .Ve -.Vb 4 -\& EVP_DigestInit(&mdctx, md); +.Vb 6 +\& EVP_MD_CTX_init(&mdctx); +\& EVP_DigestInit_ex(&mdctx, md, NULL); \& EVP_DigestUpdate(&mdctx, mess1, strlen(mess1)); \& EVP_DigestUpdate(&mdctx, mess2, strlen(mess2)); -\& EVP_DigestFinal(&mdctx, md_value, &md_len); +\& EVP_DigestFinal_ex(&mdctx, md_value, &md_len); +\& EVP_MD_CTX_cleanup(&mdctx); .Ve .Vb 4 \& printf("Digest is: "); @@ -328,16 +384,9 @@ digest name passed on the command line. .Ve .SH "BUGS" .IX Header "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. -.PP The link between digests and signing algorithms results in a situation where \&\fIEVP_sha1()\fR must be used with \s-1RSA\s0 and \fIEVP_dss1()\fR must be used with \s-1DSS\s0 even though they are identical digests. -.PP -The size of an \fB\s-1EVP_MD_CTX\s0\fR structure is determined at compile time: this results -in code that must be recompiled if the size of \fB\s-1EVP_MD_CTX\s0\fR increases. .SH "SEE ALSO" .IX Header "SEE ALSO" evp(3), hmac(3), md2(3), @@ -347,3 +396,11 @@ sha(3), dgst(1) .IX Header "HISTORY" \&\fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR and \fIEVP_DigestFinal()\fR are available in all versions of SSLeay and OpenSSL. +.PP +\&\fIEVP_MD_CTX_init()\fR, \fIEVP_MD_CTX_create()\fR, \fIEVP_MD_CTX_copy_ex()\fR, +\&\fIEVP_MD_CTX_cleanup()\fR, \fIEVP_MD_CTX_destroy()\fR, \fIEVP_DigestInit_ex()\fR +and \fIEVP_DigestFinal_ex()\fR were added in OpenSSL 0.9.7. +.PP +\&\fIEVP_md_null()\fR, \fIEVP_md2()\fR, \fIEVP_md5()\fR, \fIEVP_sha()\fR, \fIEVP_sha1()\fR, +\&\fIEVP_dss()\fR, \fIEVP_dss1()\fR, \fIEVP_mdc2()\fR and \fIEVP_ripemd160()\fR were +changed to return truely const \s-1EVP_MD\s0 * in OpenSSL 0.9.7. |
