-.\" $OpenBSD: EVP_DigestInit.3,v 1.25 2023/04/23 18:24:01 job Exp $
+.\" $OpenBSD: EVP_DigestInit.3,v 1.26 2023/08/11 18:08:43 schwarze Exp $
.\" full merge up to: OpenSSL 7f572e95 Dec 2 13:57:04 2015 +0000
-.\" selective merge up to: OpenSSL a95d7574 Jul 2 12:16:38 2017 -0400
+.\" selective merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
.\"
.\" This file is a derived work.
.\" The changes are covered by the following Copyright and license:
.\" 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>
-.\" and Richard Levitte <levitte@openssl.org>.
-.\" Copyright (c) 2000-2004, 2009, 2012-2016 The OpenSSL Project.
+.\" The original file was written by Dr. Stephen Henson <steve@openssl.org>,
+.\" Richard Levitte <levitte@openssl.org>,
+.\" Paul Yang <yang.yang@baishancloud.com>, and
+.\" Antoine Salon <asalon@vmware.com>.
+.\" Copyright (c) 2000-2004, 2009, 2012-2016, 2018, 2019 The OpenSSL Project.
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd $Mdocdate: April 23 2023 $
+.Dd $Mdocdate: August 11 2023 $
.Dt EVP_DIGESTINIT 3
.Os
.Sh NAME
.Nm EVP_MD_CTX_cleanup ,
.Nm EVP_MD_CTX_destroy ,
.Nm EVP_MD_CTX_ctrl ,
+.Nm EVP_MD_CTX_set_flags ,
+.Nm EVP_MD_CTX_clear_flags ,
+.Nm EVP_MD_CTX_test_flags ,
.Nm EVP_DigestInit_ex ,
.Nm EVP_DigestUpdate ,
.Nm EVP_DigestFinal_ex ,
.Nm EVP_MD_pkey_type ,
.Nm EVP_MD_size ,
.Nm EVP_MD_block_size ,
+.Nm EVP_MD_flags ,
.Nm EVP_MD_CTX_md ,
.Nm EVP_MD_CTX_size ,
.Nm EVP_MD_CTX_block_size ,
.Nm EVP_MD_CTX_type ,
+.Nm EVP_MD_CTX_md_data ,
+.Nm EVP_MD_CTX_pkey_ctx ,
+.Nm EVP_MD_CTX_set_pkey_ctx ,
.Nm EVP_md_null ,
.Nm EVP_md5 ,
.Nm EVP_md5_sha1 ,
.Fa "int p1"
.Fa "void* p2"
.Fc
+.Ft void
+.Fo EVP_MD_CTX_set_flags
+.Fa "EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
+.Ft void
+.Fo EVP_MD_CTX_clear_flags
+.Fa "EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
+.Ft int
+.Fo EVP_MD_CTX_test_flags
+.Fa "const EVP_MD_CTX *ctx"
+.Fa "int flags"
+.Fc
.Ft int
.Fo EVP_DigestInit_ex
.Fa "EVP_MD_CTX *ctx"
.Fo EVP_MD_block_size
.Fa "const EVP_MD *md"
.Fc
+.Ft unsigned long
+.Fo EVP_MD_flags
+.Fa "const EVP_MD *md"
+.Fc
.Ft const EVP_MD *
.Fo EVP_MD_CTX_md
.Fa "const EVP_MD_CTX *ctx"
.Fc
.Ft int
.Fo EVP_MD_CTX_size
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
.Fc
.Ft int
.Fo EVP_MD_CTX_block_size
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
.Fc
.Ft int
.Fo EVP_MD_CTX_type
-.Fa "const EVP_MD *ctx"
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft void *
+.Fo EVP_MD_CTX_md_data
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft EVP_PKEY_CTX *
+.Fo EVP_MD_CTX_pkey_ctx
+.Fa "const EVP_MD_CTX *ctx"
+.Fc
+.Ft void
+.Fo EVP_MD_CTX_set_pkey_ctx
+.Fa "EVP_MD_CTX *ctx"
+.Fa "EVP_PKEY_CTX *pctx"
.Fc
.Ft const EVP_MD *
.Fn EVP_md_null void
.Fa "const ASN1_OBJECT *o"
.Fc
.Sh DESCRIPTION
-The EVP digest routines are a high level interface to message digests
+The EVP digest routines are a high-level interface to message digests
and should be used instead of the cipher-specific functions.
.Pp
.Fn EVP_MD_CTX_new
.Fn EVP_MD_CTX_ctrl
performs digest-specific control actions on the context
.Fa ctx .
+The control command is indicated in
+.Fa cmd
+and any additional arguments in
+.Fa p1
+and
+.Fa p2 .
+.Fn EVP_MD_CTX_ctrl
+must be called after
+.Fn EVP_DigestInit_ex .
+Other restrictions may apply depending on the control type
+and digest implementation.
+.Pp
+If the
+.Fa cmd
+is
+.Dv EVP_MD_CTRL_MICALG ,
+the digest Message Integrity Check algorithm string is written to
+.Pf * p2 .
+This is used when creating S/MIME multipart/signed messages
+as specified in RFC 3851.
+.Pp
+.Fn EVP_MD_CTX_set_flags ,
+.Fn EVP_MD_CTX_clear_flags ,
+and
+.Fn EVP_MD_CTX_test_flags
+set, clear and test the following
+.Fa ctx
+flags:
+.Bl -tag -width Ds -offset 2n
+.It Dv EVP_MD_CTX_FLAG_NO_INIT
+Instruct
+.Fn EVP_DigestInit
+and similar functions not to initialise the implementation specific data.
+.It Dv EVP_MD_CTX_FLAG_ONESHOT
+Instruct the digest to optimize for one update only, if possible.
+.El
.Pp
.Fn EVP_DigestInit_ex
sets up the digest context
.Vt EVP_MD_CTX
structure.
.Pp
-.Fn EVP_MD_type
+.Fn EVP_MD_type ,
+.Fn EVP_MD_pkey_type ,
and
.Fn EVP_MD_CTX_type
return the NID of the OBJECT IDENTIFIER representing the given message
.Dv NID_sha1 .
This function is normally used when setting ASN.1 OIDs.
.Pp
+.Fn EVP_MD_CTX_md_data
+returns the digest method private data of
+.Fa ctx .
+The space was allocated and its size set with
+.Xr EVP_MD_meth_set_app_datasize 3 .
+.Pp
+.Fn EVP_MD_flags
+returns the
+.Fa md
+flags.
+These are different from the
+.Vt EVP_MD_CTX
+ones.
+See
+.Xr EVP_MD_meth_set_flags 3
+for more information.
+.Pp
.Fn EVP_MD_pkey_type
returns the NID of the public key signing algorithm associated with this
digest.
Since digests and signature algorithms are no longer linked, this
function is only retained for compatibility reasons.
.Pp
+.Fn EVP_MD_CTX_pkey_ctx
+returns the
+.Vt EVP_PKEY_CTX
+assigned to
+.Fa ctx .
+The returned pointer should not be freed by the caller.
+.Pp
+.Fn EVP_MD_CTX_set_pkey_ctx
+assigns
+.Fa pctx
+to
+.Fa ctx .
+This is usually used to provide a customized
+.Vt EVP_PKEY_CTX
+to
+.Xr EVP_DigestSignInit 3
+or
+.Xr EVP_DigestVerifyInit 3 .
+The
+.Fa pctx
+passed to this function should be freed by the caller.
+A
+.Dv NULL
+.Fa pctx
+pointer is also allowed to clear the
+.Vt EVP_PKEY_CTX
+assigned to
+.Fa ctx .
+In this case, freeing the cleared
+.Vt EVP_PKEY_CTX
+or not depends on how the
+.Vt EVP_PKEY_CTX
+was created.
+.Pp
.Fn EVP_md5 ,
.Fn EVP_sha1 ,
.Fn EVP_sha224 ,
are implemented as macros.
.Pp
The EVP interface to message digests should almost always be used
-in preference to the low level interfaces.
+in preference to the low-level interfaces.
This is because the code then becomes transparent to the digest used and
much more flexible.
.Pp
using the digest name passed on the command line.
.Bd -literal -offset indent
#include <stdio.h>
+#include <string.h>
#include <openssl/evp.h>
int
const char mess1[] = "Test Message\en";
const char mess2[] = "Hello World\en";
unsigned char md_value[EVP_MAX_MD_SIZE];
- int md_len, i;
+ unsigned int md_len, i;
if (argc <= 1) {
printf("Usage: mdtest digestname\en");
.Xr EVP_BytesToKey 3 ,
.Xr EVP_DigestSignInit 3 ,
.Xr EVP_DigestVerifyInit 3 ,
+.Xr EVP_MD_meth_new 3 ,
.Xr EVP_PKEY_CTX_set_signature_md 3 ,
.Xr EVP_PKEY_meth_set_signctx 3 ,
.Xr EVP_SignInit 3 ,
first appeared in OpenSSL 1.1.0 and have been available since
.Ox 6.3 .
.Pp
+.Fn EVP_MD_CTX_set_pkey_ctx
+first appeared in OpenSSL 1.1.1 and has been available since
+.Ox 7.1 .
+.Pp
The link between digests and signing algorithms was fixed in OpenSSL 1.0
and later, so now
.Fn EVP_sha1
projects / openbsd / commitdiff