| Current Path : /usr/opt/openssl11/share/doc/openssl/html/man3/ |
FreeBSD hs32.drive.ne.jp 9.1-RELEASE FreeBSD 9.1-RELEASE #1: Wed Jan 14 12:18:08 JST 2015 root@hs32.drive.ne.jp:/sys/amd64/compile/hs32 amd64 |
| Current File : //usr/opt/openssl11/share/doc/openssl/html/man3/BIO_f_md.html |
<?xml version="1.0" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<title>BIO_f_md</title>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<link rev="made" href="mailto:root@hsxx.drive.ne.jp" />
</head>
<body style="background-color: white">
<!-- INDEX BEGIN -->
<div name="index">
<p><a name="__index__"></a></p>
<ul>
<li><a href="#name">NAME</a></li>
<li><a href="#synopsis">SYNOPSIS</a></li>
<li><a href="#description">DESCRIPTION</a></li>
<li><a href="#notes">NOTES</a></li>
<li><a href="#return_values">RETURN VALUES</a></li>
<li><a href="#examples">EXAMPLES</a></li>
<li><a href="#bugs">BUGS</a></li>
<li><a href="#history">HISTORY</a></li>
<li><a href="#copyright">COPYRIGHT</a></li>
</ul>
<hr name="index" />
</div>
<!-- INDEX END -->
<p>
</p>
<hr />
<h1><a name="name">NAME</a></h1>
<p>BIO_f_md, BIO_set_md, BIO_get_md, BIO_get_md_ctx - message digest BIO filter</p>
<p>
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1>
<pre>
#include <openssl/bio.h>
#include <openssl/evp.h></pre>
<pre>
const BIO_METHOD *BIO_f_md(void);
int BIO_set_md(BIO *b, EVP_MD *md);
int BIO_get_md(BIO *b, EVP_MD **mdp);
int BIO_get_md_ctx(BIO *b, EVP_MD_CTX **mdcp);</pre>
<p>
</p>
<hr />
<h1><a name="description">DESCRIPTION</a></h1>
<p><code>BIO_f_md()</code> returns the message digest BIO method. This is a filter
BIO that digests any data passed through it, it is a BIO wrapper
for the digest routines <code>EVP_DigestInit()</code>, <code>EVP_DigestUpdate()</code>
and <code>EVP_DigestFinal()</code>.</p>
<p>Any data written or read through a digest BIO using <code>BIO_read_ex()</code> and
<code>BIO_write_ex()</code> is digested.</p>
<p><code>BIO_gets()</code>, if its <strong>size</strong> parameter is large enough finishes the
digest calculation and returns the digest value. <code>BIO_puts()</code> is
not supported.</p>
<p><code>BIO_reset()</code> reinitialises a digest BIO.</p>
<p><code>BIO_set_md()</code> sets the message digest of BIO <strong>b</strong> to <strong>md</strong>: this
must be called to initialize a digest BIO before any data is
passed through it. It is a <code>BIO_ctrl()</code> macro.</p>
<p><code>BIO_get_md()</code> places the a pointer to the digest BIOs digest method
in <strong>mdp</strong>, it is a <code>BIO_ctrl()</code> macro.</p>
<p><code>BIO_get_md_ctx()</code> returns the digest BIOs context into <strong>mdcp</strong>.</p>
<p>
</p>
<hr />
<h1><a name="notes">NOTES</a></h1>
<p>The context returned by <code>BIO_get_md_ctx()</code> can be used in calls
to <code>EVP_DigestFinal()</code> and also the signature routines <code>EVP_SignFinal()</code>
and <code>EVP_VerifyFinal()</code>.</p>
<p>The context returned by <code>BIO_get_md_ctx()</code> is an internal context
structure. Changes made to this context will affect the digest
BIO itself and the context pointer will become invalid when the digest
BIO is freed.</p>
<p>After the digest has been retrieved from a digest BIO it must be
reinitialized by calling <code>BIO_reset()</code>, or <code>BIO_set_md()</code> before any more
data is passed through it.</p>
<p>If an application needs to call <code>BIO_gets()</code> or <code>BIO_puts()</code> through
a chain containing digest BIOs then this can be done by prepending
a buffering BIO.</p>
<p>Calling <code>BIO_get_md_ctx()</code> will return the context and initialize the BIO
state. This allows applications to initialize the context externally
if the standard calls such as <code>BIO_set_md()</code> are not sufficiently flexible.</p>
<p>
</p>
<hr />
<h1><a name="return_values">RETURN VALUES</a></h1>
<p><code>BIO_f_md()</code> returns the digest BIO method.</p>
<p><code>BIO_set_md()</code>, <code>BIO_get_md()</code> and <code>BIO_md_ctx()</code> return 1 for success and
0 for failure.</p>
<p>
</p>
<hr />
<h1><a name="examples">EXAMPLES</a></h1>
<p>The following example creates a BIO chain containing an SHA1 and MD5
digest BIO and passes the string "Hello World" through it. Error
checking has been omitted for clarity.</p>
<pre>
BIO *bio, *mdtmp;
char message[] = "Hello World";</pre>
<pre>
bio = BIO_new(BIO_s_null());
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
/*
* For BIO_push() we want to append the sink BIO and keep a note of
* the start of the chain.
*/
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
/* Note: mdtmp can now be discarded */
BIO_write(bio, message, strlen(message));</pre>
<p>The next example digests data by reading through a chain instead:</p>
<pre>
BIO *bio, *mdtmp;
char buf[1024];
int rdlen;</pre>
<pre>
bio = BIO_new_file(file, "rb");
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_sha1());
bio = BIO_push(mdtmp, bio);
mdtmp = BIO_new(BIO_f_md());
BIO_set_md(mdtmp, EVP_md5());
bio = BIO_push(mdtmp, bio);
do {
rdlen = BIO_read(bio, buf, sizeof(buf));
/* Might want to do something with the data here */
} while (rdlen > 0);</pre>
<p>This next example retrieves the message digests from a BIO chain and
outputs them. This could be used with the examples above.</p>
<pre>
BIO *mdtmp;
unsigned char mdbuf[EVP_MAX_MD_SIZE];
int mdlen;
int i;</pre>
<pre>
mdtmp = bio; /* Assume bio has previously been set up */
do {
EVP_MD *md;</pre>
<pre>
mdtmp = BIO_find_type(mdtmp, BIO_TYPE_MD);
if (!mdtmp)
break;
BIO_get_md(mdtmp, &md);
printf("%s digest", OBJ_nid2sn(EVP_MD_type(md)));
mdlen = BIO_gets(mdtmp, mdbuf, EVP_MAX_MD_SIZE);
for (i = 0; i < mdlen; i++) printf(":%02X", mdbuf[i]);
printf("\n");
mdtmp = BIO_next(mdtmp);
} while (mdtmp);</pre>
<pre>
BIO_free_all(bio);</pre>
<p>
</p>
<hr />
<h1><a name="bugs">BUGS</a></h1>
<p>The lack of support for <code>BIO_puts()</code> and the non standard behaviour of
<code>BIO_gets()</code> could be regarded as anomalous. It could be argued that <code>BIO_gets()</code>
and <code>BIO_puts()</code> should be passed to the next BIO in the chain and digest
the data passed through and that digests should be retrieved using a
separate <code>BIO_ctrl()</code> call.</p>
<p>
</p>
<hr />
<h1><a name="history">HISTORY</a></h1>
<p>Before OpenSSL 1.0.0., the call to <code>BIO_get_md_ctx()</code> would only work if the
BIO was initialized first.</p>
<p>
</p>
<hr />
<h1><a name="copyright">COPYRIGHT</a></h1>
<p>Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.</p>
<p>Licensed under the OpenSSL license (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
<a href="https://www.openssl.org/source/license.html">https://www.openssl.org/source/license.html</a>.</p>
</body>
</html>