366 lines
10 KiB
Groff
366 lines
10 KiB
Groff
.\" $OpenBSD: BIO_f_md.3,v 1.15 2023/04/28 16:20:01 schwarze Exp $
|
|
.\" full merge up to: OpenSSL e9b77246 Jan 20 19:58:49 2017 +0100
|
|
.\"
|
|
.\" This file is a derived work.
|
|
.\" The changes are covered by the following Copyright and license:
|
|
.\"
|
|
.\" Copyright (c) 2022, 2023 Ingo Schwarze <schwarze@openbsd.org>
|
|
.\"
|
|
.\" Permission to use, copy, modify, and distribute this software for any
|
|
.\" purpose with or without fee is hereby granted, provided that the above
|
|
.\" copyright notice and this permission notice appear in all copies.
|
|
.\"
|
|
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
.\"
|
|
.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>.
|
|
.\" Copyright (c) 2000, 2006, 2009, 2016 The OpenSSL Project.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in
|
|
.\" the documentation and/or other materials provided with the
|
|
.\" distribution.
|
|
.\"
|
|
.\" 3. All advertising materials mentioning features or use of this
|
|
.\" software must display the following acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
|
|
.\"
|
|
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
|
|
.\" endorse or promote products derived from this software without
|
|
.\" prior written permission. For written permission, please contact
|
|
.\" openssl-core@openssl.org.
|
|
.\"
|
|
.\" 5. Products derived from this software may not be called "OpenSSL"
|
|
.\" nor may "OpenSSL" appear in their names without prior written
|
|
.\" permission of the OpenSSL Project.
|
|
.\"
|
|
.\" 6. Redistributions of any form whatsoever must retain the following
|
|
.\" acknowledgment:
|
|
.\" "This product includes software developed by the OpenSSL Project
|
|
.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)"
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
|
|
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
|
.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR
|
|
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
|
|
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
|
|
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
|
|
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
|
|
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
|
|
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
|
|
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
.\"
|
|
.Dd $Mdocdate: April 28 2023 $
|
|
.Dt BIO_F_MD 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm BIO_f_md ,
|
|
.Nm BIO_set_md ,
|
|
.Nm BIO_get_md ,
|
|
.Nm BIO_get_md_ctx ,
|
|
.Nm BIO_set_md_ctx
|
|
.Nd message digest BIO filter
|
|
.Sh SYNOPSIS
|
|
.In openssl/bio.h
|
|
.In openssl/evp.h
|
|
.Ft const BIO_METHOD *
|
|
.Fo BIO_f_md
|
|
.Fa void
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_md
|
|
.Fa "BIO *b"
|
|
.Fa "EVP_MD *md"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_get_md
|
|
.Fa "BIO *b"
|
|
.Fa "EVP_MD **mdp"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_get_md_ctx
|
|
.Fa "BIO *b"
|
|
.Fa "EVP_MD_CTX **mdcp"
|
|
.Fc
|
|
.Ft long
|
|
.Fo BIO_set_md_ctx
|
|
.Fa "BIO *b"
|
|
.Fa "EVP_MD_CTX *mdc"
|
|
.Fc
|
|
.Sh DESCRIPTION
|
|
.Fn BIO_f_md
|
|
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
|
|
.Xr EVP_DigestInit 3 ,
|
|
.Xr EVP_DigestUpdate 3 ,
|
|
and
|
|
.Xr EVP_DigestFinal 3 .
|
|
.Pp
|
|
.Fn BIO_set_md
|
|
sets the message digest of
|
|
.Fa b
|
|
to
|
|
.Fa md
|
|
and initializes it using
|
|
.Xr EVP_DigestInit_ex 3 .
|
|
Calling this function is required before any data is passed through
|
|
.Fa b .
|
|
.Pp
|
|
.Fn BIO_get_md
|
|
places a pointer to the digest method of
|
|
.Fa b
|
|
into
|
|
.Pf * Fa mdp .
|
|
.Pp
|
|
Any data written or read through a digest BIO using
|
|
.Xr BIO_read 3
|
|
and
|
|
.Xr BIO_write 3
|
|
is digested.
|
|
.Pp
|
|
.Xr BIO_gets 3 ,
|
|
if its
|
|
.Sy size
|
|
parameter is large enough,
|
|
finishes the digest calculation and returns the digest value.
|
|
.Xr BIO_puts 3
|
|
is
|
|
not supported.
|
|
If an application needs to call
|
|
.Xr BIO_gets 3
|
|
or
|
|
.Xr BIO_puts 3
|
|
through a chain containing digest BIOs,
|
|
this can be done by prepending a buffering BIO.
|
|
.Pp
|
|
After the digest has been retrieved from a digest BIO, call
|
|
.Xr BIO_reset 3
|
|
to reinitialize it and any BIOs following it in its chain
|
|
before passing any more data through it.
|
|
If no subsequent BIOs require reinitialization,
|
|
.Fn BIO_set_md
|
|
can be used instead of
|
|
.Xr BIO_reset 3 .
|
|
.Pp
|
|
.Fn BIO_get_md_ctx
|
|
places a pointer to the digest context of
|
|
.Fa b
|
|
into
|
|
.Pf * Fa mdcp
|
|
and marks the BIO as initialized without actually initializing it.
|
|
Unless
|
|
.Fn BIO_set_md
|
|
was already called on
|
|
.Fa b ,
|
|
the caller becomes responsible for initializing the digest context with
|
|
.Xr EVP_DigestInit_ex 3 .
|
|
.Pp
|
|
The context returned by
|
|
.Fn BIO_get_md_ctx
|
|
can be used in calls to
|
|
.Xr EVP_DigestFinal 3
|
|
and also in the signature routines
|
|
.Xr EVP_SignFinal 3
|
|
and
|
|
.Xr EVP_VerifyFinal 3 .
|
|
.Pp
|
|
The context returned by
|
|
.Fn BIO_get_md_ctx
|
|
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.
|
|
.Pp
|
|
.Fn BIO_set_md_ctx
|
|
replaces the digest context of
|
|
.Fa b
|
|
with
|
|
.Fa mdc .
|
|
Calling this function is usually not necessary
|
|
because creating a digest BIO with
|
|
.Xr BIO_new 3
|
|
automatically creates a digest context and stores it internally.
|
|
Before calling
|
|
.Fn BIO_set_md_ctx ,
|
|
the caller has to retrieve the old context using
|
|
.Fn BIO_get_md_ctx ,
|
|
and the caller also becomes responsible for calling
|
|
.Xr EVP_MD_CTX_free 3
|
|
on the old context.
|
|
Unless
|
|
.Fa mdc
|
|
is already initialized, the caller needs to initialize it after calling
|
|
.Fn BIO_set_md_ctx
|
|
using either
|
|
.Fn BIO_set_md
|
|
or
|
|
.Xr EVP_DigestInit 3 .
|
|
.Pp
|
|
When a chain containing a message digest BIO is copied with
|
|
.Xr BIO_dup_chain 3 ,
|
|
.Xr EVP_MD_CTX_copy_ex 3
|
|
is called internally to automatically copy the message digest context
|
|
from the existing BIO object to the new one,
|
|
and the init flag that can be retrieved with
|
|
.Xr BIO_get_init 3
|
|
is set to 1.
|
|
.Pp
|
|
.Xr BIO_ctrl 3
|
|
.Fa cmd
|
|
arguments correspond to macros as follows:
|
|
.Bl -column BIO_C_GET_MD_CTX "corresponding macro" -offset 3n
|
|
.It Fa cmd No constant Ta corresponding macro
|
|
.It Dv BIO_C_GET_MD Ta Fn BIO_get_md
|
|
.It Dv BIO_C_GET_MD_CTX Ta Fn BIO_get_md_ctx
|
|
.It Dv BIO_C_SET_MD Ta Fn BIO_set_md
|
|
.It Dv BIO_C_SET_MD_CTX Ta Fn BIO_set_md_ctx
|
|
.It Dv BIO_CTRL_RESET Ta Xr BIO_reset 3
|
|
.El
|
|
.Sh RETURN VALUES
|
|
.Fn BIO_f_md
|
|
returns the digest BIO method.
|
|
.Pp
|
|
When called on a message digest BIO object,
|
|
.Xr BIO_method_type 3
|
|
returns the constant
|
|
.Dv BIO_TYPE_MD
|
|
and
|
|
.Xr BIO_method_name 3
|
|
returns a pointer to the static string
|
|
.Qq message digest .
|
|
.Pp
|
|
.Fn BIO_set_md
|
|
returns 1 on success or 0 if
|
|
.Xr EVP_DigestInit_ex 3
|
|
fails.
|
|
.Pp
|
|
.Fn BIO_get_md
|
|
and
|
|
.Fn BIO_set_md_ctx
|
|
return 1 on success or 0 if
|
|
.Fa b
|
|
is not initialized.
|
|
.Pp
|
|
.Fn BIO_get_md_ctx
|
|
returns 1 on success or 0 on failure,
|
|
but the current implementation cannot actually fail.
|
|
.Sh EXAMPLES
|
|
The following example creates a BIO chain containing a SHA-1 and MD5
|
|
digest BIO and passes the string "Hello World" through it.
|
|
Error checking has been omitted for clarity.
|
|
.Bd -literal -offset 2n
|
|
BIO *bio, *mdtmp;
|
|
const char message[] = "Hello World";
|
|
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));
|
|
.Ed
|
|
.Pp
|
|
The next example digests data by reading through a chain instead:
|
|
.Bd -literal -offset 2n
|
|
BIO *bio, *mdtmp;
|
|
char buf[1024];
|
|
int rdlen;
|
|
|
|
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);
|
|
.Ed
|
|
.Pp
|
|
This next example retrieves the message digests from a BIO chain
|
|
and outputs them.
|
|
This could be used with the examples above.
|
|
.Bd -literal -offset 2n
|
|
BIO *mdtmp;
|
|
unsigned char mdbuf[EVP_MAX_MD_SIZE];
|
|
int mdlen;
|
|
int i;
|
|
|
|
mdtmp = bio; /* Assume bio has previously been set up */
|
|
do {
|
|
EVP_MD *md;
|
|
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("\en");
|
|
mdtmp = BIO_next(mdtmp);
|
|
} while(mdtmp);
|
|
BIO_free_all(bio);
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr BIO_new 3 ,
|
|
.Xr EVP_DigestInit 3
|
|
.Sh HISTORY
|
|
.Fn BIO_f_md ,
|
|
.Fn BIO_set_md ,
|
|
and
|
|
.Fn BIO_get_md
|
|
first appeared in SSLeay 0.6.0.
|
|
.Fn BIO_get_md_ctx
|
|
first appeared in SSLeay 0.8.1.
|
|
These functions have been available since
|
|
.Ox 2.4 .
|
|
.Pp
|
|
.Fn BIO_set_md_ctx
|
|
first appeared in OpenSSL 0.9.7e and has been available since
|
|
.Ox 3.8 .
|
|
.Pp
|
|
Before OpenSSL 1.0.0, the call to
|
|
.Fn BIO_get_md_ctx
|
|
would only work if the
|
|
.Vt BIO
|
|
had been initialized, for example by calling
|
|
.Fn BIO_set_md .
|
|
.Sh BUGS
|
|
The lack of support for
|
|
.Xr BIO_puts 3
|
|
and the non-standard behaviour of
|
|
.Xr BIO_gets 3
|
|
could be regarded as anomalous.
|
|
It could be argued that
|
|
.Xr BIO_gets 3
|
|
and
|
|
.Xr BIO_puts 3
|
|
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
|
|
.Xr BIO_ctrl 3
|
|
call.
|