Local adjustments for OpenSSL-1.0.1j.
[dragonfly.git] / secure / lib / libcrypto / man / EVP_DigestInit.3
index 5d93f7b..52b5a10 100644 (file)
@@ -1,4 +1,4 @@
-.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.19)
+.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.20)
 .\"
 .\" Standard preamble:
 .\" ========================================================================
 .\" ========================================================================
 .\"
 .IX Title "EVP_DigestInit 3"
-.TH EVP_DigestInit 3 "2012-03-14" "1.0.1" "OpenSSL"
+.TH EVP_DigestInit 3 "2014-06-05" "1.0.1h" "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"
@@ -153,24 +154,23 @@ EVP digest routines
 \& int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
 \& void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
 \&
-\& int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);  
+\& int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
 \&
 \& int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
 \& int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
 \&        unsigned int *s);
 \&
-\& int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);  
+\& 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,17 @@ 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. Note: there is 
+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
@@ -281,9 +288,8 @@ success and 0 for failure.
 \&\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.
 .PP
-\&\fIEVP_MD_size()\fR, \fIEVP_MD_block_size()\fR, EVP_MD_CTX_size(e), \fIEVP_MD_size()\fR,
-\&\fIEVP_MD_CTX_block_size()\fR        and \fIEVP_MD_block_size()\fR return the digest or block
-size in bytes.
+\&\fIEVP_MD_size()\fR, \fIEVP_MD_block_size()\fR, \fIEVP_MD_CTX_size()\fR and
+\&\fIEVP_MD_CTX_block_size()\fR return the digest or block size in bytes.
 .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 return pointers to the
@@ -297,21 +303,37 @@ 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.
 .PP
-The functions \fIEVP_DigestInit()\fR, \fIEVP_DigestFinal()\fR and \fIEVP_MD_CTX_copy()\fR are 
+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 
+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.
+.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
@@ -323,7 +345,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";
@@ -344,23 +366,27 @@ 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]);
+\& for(i = 0; i < md_len; i++)
+\&        printf("%02x", md_value[i]);
 \& printf("\en");
+\&
+\& /* Call this once before exit. */
+\& EVP_cleanup();
+\& exit(0);
 \& }
 .Ve
 .SH "SEE ALSO"
 .IX Header "SEE ALSO"
-\&\fIevp\fR\|(3), \fIhmac\fR\|(3), \fImd2\fR\|(3),
-\&\fImd5\fR\|(3), \fImdc2\fR\|(3), \fIripemd\fR\|(3),
-\&\fIsha\fR\|(3), \fIdgst\fR\|(1)
+\&\fIdgst\fR\|(1),
+\&\fIevp\fR\|(3)
 .SH "HISTORY"
 .IX Header "HISTORY"
 \&\fIEVP_DigestInit()\fR, \fIEVP_DigestUpdate()\fR and \fIEVP_DigestFinal()\fR are
@@ -375,7 +401,7 @@ and \fIEVP_DigestFinal_ex()\fR were added in OpenSSL 0.9.7.
 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
+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