sync code with last improvements from OpenBSD
This commit is contained in:
parent
454dab66ed
commit
27298272ec
GPG key ID:
F42C07F07E2E35B7
237 changed files with 4666 additions and 2149 deletions
|
|
@ -1,11 +1,11 @@
|
|||
.\" $OpenBSD: EVP_DigestInit.3,v 1.25 2023/04/23 18:24:01 job Exp $
|
||||
.\" $OpenBSD: EVP_DigestInit.3,v 1.28 2023/08/14 14:22:32 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:
|
||||
.\"
|
||||
.\" Copyright (c) 2019 Ingo Schwarze <schwarze@openbsd.org>
|
||||
.\" Copyright (c) 2019, 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
|
||||
|
|
@ -19,9 +19,11 @@
|
|||
.\" 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
|
||||
|
|
@ -68,7 +70,7 @@
|
|||
.\" 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 14 2023 $
|
||||
.Dt EVP_DIGESTINIT 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
|
|
@ -80,6 +82,9 @@
|
|||
.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 ,
|
||||
|
|
@ -93,10 +98,14 @@
|
|||
.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 ,
|
||||
|
|
@ -141,10 +150,25 @@
|
|||
.Ft int
|
||||
.Fo EVP_MD_CTX_ctrl
|
||||
.Fa "EVP_MD_CTX *ctx"
|
||||
.Fa "int cmd"
|
||||
.Fa "int command"
|
||||
.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"
|
||||
|
|
@ -210,21 +234,38 @@
|
|||
.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
|
||||
|
|
@ -261,7 +302,7 @@
|
|||
.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
|
||||
|
|
@ -298,8 +339,68 @@ and
|
|||
respectively.
|
||||
.Pp
|
||||
.Fn EVP_MD_CTX_ctrl
|
||||
performs digest-specific control actions on the context
|
||||
performs the digest-specific control
|
||||
.Fa command
|
||||
with the command-specific arguments
|
||||
.Fa p1
|
||||
and
|
||||
.Fa p2
|
||||
on
|
||||
.Fa ctx ,
|
||||
which needs to already be set up with
|
||||
.Fn EVP_DigestInit_ex
|
||||
before calling this function.
|
||||
Other restrictions may apply depending on the control
|
||||
.Fa command
|
||||
and digest implementation.
|
||||
.Pp
|
||||
If the
|
||||
.Fa command
|
||||
is
|
||||
.Dv EVP_MD_CTRL_MICALG ,
|
||||
.Fa p1
|
||||
is ignored and
|
||||
.Fa p2
|
||||
is an output argument of the type
|
||||
.Fa "char **p2" .
|
||||
A string specifying the digest Message Integrity Check algorithm
|
||||
is allocated and a pointer to this string is returned in
|
||||
.Pf * Fa p2 .
|
||||
It is the responsibility of the caller to
|
||||
.Xr free 3
|
||||
.Pf * Fa p2
|
||||
when it is no longer needed.
|
||||
This
|
||||
.Fa command
|
||||
is used by
|
||||
.Xr SMIME_write_ASN1 3
|
||||
when creating S/MIME multipart/signed messages as specified in RFC 3851.
|
||||
.Pp
|
||||
.Fn EVP_MD_CTX_set_flags
|
||||
sets and
|
||||
.Fn EVP_MD_CTX_clear_flags
|
||||
clears all the flag bits in
|
||||
.Fa ctx
|
||||
that are set in the
|
||||
.Fa flags
|
||||
argument.
|
||||
.Fn EVP_MD_CTX_test_flags
|
||||
tests which of the flag bits that are set in the
|
||||
.Fa flags
|
||||
argument are also set in
|
||||
.Fa ctx .
|
||||
Possible flag bits are:
|
||||
.Bl -tag -width Ds -offset 2n
|
||||
.It Dv EVP_MD_CTX_FLAG_NO_INIT
|
||||
Instruct
|
||||
.Fn EVP_DigestInit_ex
|
||||
and functions calling it not to initialise the internal data
|
||||
that is specific to the digest method and its implementation.
|
||||
.It Dv EVP_MD_CTX_FLAG_ONESHOT
|
||||
Instruct the digest to optimize for one update only, if possible.
|
||||
For digest algorithms built into the library, this flag usually
|
||||
has no effect.
|
||||
.El
|
||||
.Pp
|
||||
.Fn EVP_DigestInit_ex
|
||||
sets up the digest context
|
||||
|
|
@ -434,15 +535,29 @@ structure.
|
|||
.Fn EVP_MD_type
|
||||
and
|
||||
.Fn EVP_MD_CTX_type
|
||||
return the NID of the OBJECT IDENTIFIER representing the given message
|
||||
digest when passed an
|
||||
.Vt EVP_MD
|
||||
structure.
|
||||
return the NID of the OBJECT IDENTIFIER representing the message digest.
|
||||
For example
|
||||
.Fn EVP_MD_type EVP_sha1()
|
||||
returns
|
||||
.Dv NID_sha1 .
|
||||
This function is normally used when setting ASN.1 OIDs.
|
||||
These functions are 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
|
||||
|
|
@ -454,6 +569,56 @@ is associated with RSA so this will return
|
|||
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 normally used to provide a customized
|
||||
.Vt EVP_PKEY_CTX
|
||||
to
|
||||
.Xr EVP_DigestSignInit 3
|
||||
or
|
||||
.Xr EVP_DigestVerifyInit 3 .
|
||||
The caller retains ownership of the
|
||||
.Fa pctx
|
||||
passed to this function and is responsible for freeing it
|
||||
when it is no longer needed.
|
||||
.Pp
|
||||
If the
|
||||
.Fa ctx
|
||||
already contains a
|
||||
.Vt EVP_PKEY_CTX
|
||||
when this function is called, that old
|
||||
.Vt EVP_PKEY_CTX
|
||||
is freed if it was created internally, but if it was also installed with
|
||||
.Fn EVP_MD_CTX_set_pkey_ctx ,
|
||||
the pointer to the old
|
||||
.Vt EVP_PKEY_CTX
|
||||
is merely replaced by the new pointer and ownership of the old
|
||||
.Vt EVP_PKEY_CTX
|
||||
remains with the previous caller.
|
||||
.Pp
|
||||
Passing a
|
||||
.Dv NULL
|
||||
pointer for the
|
||||
.Fa pctx
|
||||
argument is also allowed.
|
||||
In that case, any
|
||||
.Vt EVP_PKEY_CTX
|
||||
already assigned to
|
||||
.Fa ctx
|
||||
is dissociated from it as described above, but no new
|
||||
.Vt EVP_PKEY_CTX
|
||||
is assigned.
|
||||
.Pp
|
||||
.Fn EVP_md5 ,
|
||||
.Fn EVP_sha1 ,
|
||||
.Fn EVP_sha224 ,
|
||||
|
|
@ -502,7 +667,7 @@ and
|
|||
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
|
||||
|
|
@ -559,6 +724,12 @@ and
|
|||
.Fn EVP_MD_CTX_copy
|
||||
return 1 for success or 0 for failure.
|
||||
.Pp
|
||||
.Fn EVP_MD_CTX_test_flags
|
||||
returns the bitwise OR of the
|
||||
.Fa flags
|
||||
argument and the flags set in
|
||||
.Fa ctx .
|
||||
.Pp
|
||||
.Fn EVP_MD_type ,
|
||||
.Fn EVP_MD_pkey_type ,
|
||||
and
|
||||
|
|
@ -610,6 +781,7 @@ This example digests the data "Test Message\en" and "Hello World\en",
|
|||
using the digest name passed on the command line.
|
||||
.Bd -literal -offset indent
|
||||
#include <stdio.h>
|
||||
#include <string.h>
|
||||
#include <openssl/evp.h>
|
||||
|
||||
int
|
||||
|
|
@ -620,7 +792,7 @@ main(int argc, char *argv[])
|
|||
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");
|
||||
|
|
@ -655,8 +827,10 @@ main(int argc, char *argv[])
|
|||
.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_sha3_224 3 ,
|
||||
.Xr EVP_SignInit 3 ,
|
||||
.Xr EVP_sm3 3 ,
|
||||
.Xr EVP_VerifyInit 3 ,
|
||||
|
|
@ -715,6 +889,9 @@ first appeared in OpenSSL 0.9.5 and has been available since
|
|||
.Fn EVP_MD_CTX_create ,
|
||||
.Fn EVP_MD_CTX_cleanup ,
|
||||
.Fn EVP_MD_CTX_destroy ,
|
||||
.Fn EVP_MD_CTX_set_flags ,
|
||||
.Fn EVP_MD_CTX_clear_flags ,
|
||||
.Fn EVP_MD_CTX_test_flags ,
|
||||
.Fn EVP_DigestInit_ex ,
|
||||
.Fn EVP_DigestFinal_ex ,
|
||||
.Fn EVP_Digest ,
|
||||
|
|
@ -732,11 +909,10 @@ first appeared in OpenSSL 0.9.7h and 0.9.8a
|
|||
and have been available since
|
||||
.Ox 4.0 .
|
||||
.Pp
|
||||
.Fn EVP_sha512_224
|
||||
and
|
||||
.Fn EVP_sha512_256
|
||||
first appeared in OpenSSL 1.1.1 and has been available since
|
||||
.Ox 7.4 .
|
||||
.Fn EVP_MD_flags
|
||||
first appeared in OpenSSL 1.0.0
|
||||
and has been available since
|
||||
.Ox 4.9 .
|
||||
.Pp
|
||||
.Fn EVP_MD_CTX_ctrl
|
||||
first appeared in OpenSSL 1.1.0 and has been available since
|
||||
|
|
@ -750,6 +926,21 @@ and
|
|||
first appeared in OpenSSL 1.1.0 and have been available since
|
||||
.Ox 6.3 .
|
||||
.Pp
|
||||
.Fn EVP_MD_CTX_md_data
|
||||
and
|
||||
.Fn EVP_MD_CTX_pkey_ctx
|
||||
first appeared in OpenSSL 1.1.0 and
|
||||
.Fn EVP_MD_CTX_set_pkey_ctx
|
||||
in OpenSSL 1.1.1.
|
||||
These functions have been available since
|
||||
.Ox 7.1 .
|
||||
.Pp
|
||||
.Fn EVP_sha512_224
|
||||
and
|
||||
.Fn EVP_sha512_256
|
||||
first appeared in OpenSSL 1.1.1 and have been available since
|
||||
.Ox 7.4 .
|
||||
.Pp
|
||||
The link between digests and signing algorithms was fixed in OpenSSL 1.0
|
||||
and later, so now
|
||||
.Fn EVP_sha1
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue