diff options
Diffstat (limited to 'secure/lib/libcrypto/man/EVP_DigestInit.3')
| -rw-r--r-- | secure/lib/libcrypto/man/EVP_DigestInit.3 | 89 |
1 files changed, 58 insertions, 31 deletions
diff --git a/secure/lib/libcrypto/man/EVP_DigestInit.3 b/secure/lib/libcrypto/man/EVP_DigestInit.3 index e7c79a465027..f5b94c0f4296 100644 --- a/secure/lib/libcrypto/man/EVP_DigestInit.3 +++ b/secure/lib/libcrypto/man/EVP_DigestInit.3 @@ -1,4 +1,4 @@ -.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07) +.\" Automatically generated by Pod::Man 2.23 (Pod::Simple 3.22) .\" .\" Standard preamble: .\" ======================================================================== @@ -124,7 +124,7 @@ .\" ======================================================================== .\" .IX Title "EVP_DigestInit 3" -.TH EVP_DigestInit 3 "2010-12-02" "0.9.8q" "OpenSSL" +.TH EVP_DigestInit 3 "2012-05-10" "1.0.1c" "OpenSSL" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l @@ -134,7 +134,8 @@ EVP_MD_CTX_init, EVP_MD_CTX_create, EVP_DigestInit_ex, EVP_DigestUpdate, EVP_DigestFinal_ex, EVP_MD_CTX_cleanup, EVP_MD_CTX_destroy, EVP_MAX_MD_SIZE, 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_md_null, EVP_md2, EVP_md5, EVP_sha, EVP_sha1, EVP_sha224, EVP_sha256, +EVP_sha384, EVP_sha512, EVP_dss, EVP_dss1, EVP_mdc2, EVP_ripemd160, EVP_get_digestbyname, EVP_get_digestbynid, EVP_get_digestbyobj \- EVP digest routines .SH "SYNOPSIS" @@ -161,16 +162,15 @@ EVP digest routines \& \& int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in); \& -\& #define EVP_MAX_MD_SIZE (16+20) /* The SSLv3 md5+sha1 type */ +\& #define EVP_MAX_MD_SIZE 64 /* SHA512 */ \& +\& int EVP_MD_type(const EVP_MD *md); +\& int EVP_MD_pkey_type(const EVP_MD *md); +\& int EVP_MD_size(const EVP_MD *md); +\& int EVP_MD_block_size(const EVP_MD *md); \& -\& #define EVP_MD_type(e) ((e)\->type) -\& #define EVP_MD_pkey_type(e) ((e)\->pkey_type) -\& #define EVP_MD_size(e) ((e)\->md_size) -\& #define EVP_MD_block_size(e) ((e)\->block_size) -\& -\& #define EVP_MD_CTX_md(e) (e)\->digest) -\& #define EVP_MD_CTX_size(e) EVP_MD_size((e)\->digest) +\& const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx); +\& #define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e)) \& #define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)\->digest) \& #define EVP_MD_CTX_type(e) EVP_MD_type((e)\->digest) \& @@ -184,6 +184,11 @@ EVP digest routines \& const EVP_MD *EVP_mdc2(void); \& const EVP_MD *EVP_ripemd160(void); \& +\& const EVP_MD *EVP_sha224(void); +\& const EVP_MD *EVP_sha256(void); +\& const EVP_MD *EVP_sha384(void); +\& const EVP_MD *EVP_sha512(void); +\& \& const EVP_MD *EVP_get_digestbyname(const char *name); \& #define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a)) \& #define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a)) @@ -252,15 +257,19 @@ normally used when setting \s-1ASN1\s0 OIDs. .PP \&\fIEVP_MD_pkey_type()\fR returns the \s-1NID\s0 of the public key signing algorithm associated with this digest. For example \fIEVP_sha1()\fR is associated with \s-1RSA\s0 so this will -return \fBNID_sha1WithRSAEncryption\fR. This \*(L"link\*(R" between digests and signature -algorithms may not be retained in future versions of OpenSSL. +return \fBNID_sha1WithRSAEncryption\fR. Since digests and signature algorithms +are no longer linked this function is only retained for compatibility +reasons. .PP -\&\fIEVP_md2()\fR, \fIEVP_md5()\fR, \fIEVP_sha()\fR, \fIEVP_sha1()\fR, \fIEVP_mdc2()\fR and \fIEVP_ripemd160()\fR -return \fB\s-1EVP_MD\s0\fR structures for the \s-1MD2\s0, \s-1MD5\s0, \s-1SHA\s0, \s-1SHA1\s0, \s-1MDC2\s0 and \s-1RIPEMD160\s0 digest -algorithms respectively. The associated signature algorithm is \s-1RSA\s0 in each case. +\&\fIEVP_md2()\fR, \fIEVP_md5()\fR, \fIEVP_sha()\fR, \fIEVP_sha1()\fR, \fIEVP_sha224()\fR, \fIEVP_sha256()\fR, +\&\fIEVP_sha384()\fR, \fIEVP_sha512()\fR, \fIEVP_mdc2()\fR and \fIEVP_ripemd160()\fR return \fB\s-1EVP_MD\s0\fR +structures for the \s-1MD2\s0, \s-1MD5\s0, \s-1SHA\s0, \s-1SHA1\s0, \s-1SHA224\s0, \s-1SHA256\s0, \s-1SHA384\s0, \s-1SHA512\s0, \s-1MDC2\s0 +and \s-1RIPEMD160\s0 digest algorithms respectively. .PP \&\fIEVP_dss()\fR and \fIEVP_dss1()\fR return \fB\s-1EVP_MD\s0\fR structures for \s-1SHA\s0 and \s-1SHA1\s0 digest -algorithms but using \s-1DSS\s0 (\s-1DSA\s0) for the signature algorithm. +algorithms but using \s-1DSS\s0 (\s-1DSA\s0) for the signature algorithm. Note: there is +no need to use these pseudo-digests in OpenSSL 1.0.0 and later, they are +however retained for compatibility. .PP \&\fIEVP_md_null()\fR is a \*(L"null\*(R" message digest that does nothing: i.e. the hash it returns is of zero length. @@ -295,8 +304,8 @@ The \fB\s-1EVP\s0\fR interface to message digests should almost always be used i preference to the low level interfaces. This is because the code then becomes 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. +New applications should use the \s-1SHA2\s0 digest algorithms such as \s-1SHA256\s0. +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. @@ -310,6 +319,22 @@ 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. +.PP +Stack allocation of \s-1EVP_MD_CTX\s0 structures is common, for example: +.PP +.Vb 2 +\& EVP_MD_CTX mctx; +\& EVP_MD_CTX_init(&mctx); +.Ve +.PP +This will cause binary compatibility issues if the size of \s-1EVP_MD_CTX\s0 +structure changes (this will only happen with a major release of OpenSSL). +Applications wishing to avoid this should use \fIEVP_MD_CTX_create()\fR instead: +.PP +.Vb 2 +\& EVP_MD_CTX *mctx; +\& mctx = EVP_MD_CTX_create(); +.Ve .SH "EXAMPLE" .IX Header "EXAMPLE" This example digests the data \*(L"Test Message\en\*(R" and \*(L"Hello World\en\*(R", using the @@ -321,7 +346,7 @@ digest name passed on the command line. \& \& main(int argc, char *argv[]) \& { -\& EVP_MD_CTX mdctx; +\& EVP_MD_CTX *mdctx; \& const EVP_MD *md; \& char mess1[] = "Test Message\en"; \& char mess2[] = "Hello World\en"; @@ -342,23 +367,18 @@ digest name passed on the command line. \& exit(1); \& } \& -\& 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_ex(&mdctx, md_value, &md_len); -\& EVP_MD_CTX_cleanup(&mdctx); +\& mdctx = EVP_MD_CTX_create(); +\& EVP_DigestInit_ex(mdctx, md, NULL); +\& EVP_DigestUpdate(mdctx, mess1, strlen(mess1)); +\& EVP_DigestUpdate(mdctx, mess2, strlen(mess2)); +\& EVP_DigestFinal_ex(mdctx, md_value, &md_len); +\& EVP_MD_CTX_destroy(mdctx); \& \& printf("Digest is: "); \& for(i = 0; i < md_len; i++) printf("%02x", md_value[i]); \& printf("\en"); \& } .Ve -.SH "BUGS" -.IX Header "BUGS" -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. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fIevp\fR\|(3), \fIhmac\fR\|(3), \fImd2\fR\|(3), @@ -376,3 +396,10 @@ and \fIEVP_DigestFinal_ex()\fR were added in OpenSSL 0.9.7. \&\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. +.PP +The link between digests and signing algorithms was fixed in OpenSSL 1.0 and +later, so now \fIEVP_sha1()\fR can be used with \s-1RSA\s0 and \s-1DSA\s0, there is no need to +use \fIEVP_dss1()\fR any more. +.PP +OpenSSL 1.0 and later does not include the \s-1MD2\s0 digest algorithm in the +default configuration due to its security weaknesses. |