From 8d2509dc967437e1546523d3ec395a30e45c0e2b Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 13 Jul 2022 19:10:40 +0000 Subject: [PATCH] Write documentation for EVP_PKEY_check(3), EVP_PKEY_public_check(3), EVP_PKEY_param_check(3), and EVP_PKEY_security_bits(3) from scratch. Move the documentation of EVP_PKEY_size(3) and EVP_PKEY_bits(3) to the new manual page EVP_PKEY_size(3). Merge the documentation of the related function pointers from the OpenSSL 1.1.1 branch, which is still under a free license. OK tb@ on the new page EVP_PKEY_size(3). --- lib/libcrypto/man/EVP_PKEY_asn1_new.3 | 86 +++++++++- lib/libcrypto/man/EVP_PKEY_check.3 | 149 +++++++++++++++++ lib/libcrypto/man/EVP_PKEY_meth_new.3 | 48 +++++- lib/libcrypto/man/EVP_PKEY_size.3 | 224 ++++++++++++++++++++++++++ lib/libcrypto/man/EVP_SignInit.3 | 41 +---- 5 files changed, 504 insertions(+), 44 deletions(-) create mode 100644 lib/libcrypto/man/EVP_PKEY_check.3 create mode 100644 lib/libcrypto/man/EVP_PKEY_size.3 diff --git a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 b/lib/libcrypto/man/EVP_PKEY_asn1_new.3 index 75d25d7f113..d9947ad743d 100644 --- a/lib/libcrypto/man/EVP_PKEY_asn1_new.3 +++ b/lib/libcrypto/man/EVP_PKEY_asn1_new.3 @@ -1,8 +1,9 @@ -.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.7 2021/11/06 15:00:25 schwarze Exp $ +.\" $OpenBSD: EVP_PKEY_asn1_new.3,v 1.8 2022/07/13 19:10:40 schwarze Exp $ .\" selective merge up to: .\" OpenSSL man3/EVP_PKEY_ASN1_METHOD b0004708 Nov 1 00:45:24 2017 +0800 .\" .\" This file was written by Richard Levitte +.\" and Paul Yang . .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -49,7 +50,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 6 2021 $ +.Dd $Mdocdate: July 13 2022 $ .Dt EVP_PKEY_ASN1_NEW 3 .Os .Sh NAME @@ -62,7 +63,11 @@ .Nm EVP_PKEY_asn1_set_private , .Nm EVP_PKEY_asn1_set_param , .Nm EVP_PKEY_asn1_set_free , -.Nm EVP_PKEY_asn1_set_ctrl +.Nm EVP_PKEY_asn1_set_ctrl , +.Nm EVP_PKEY_asn1_set_check , +.Nm EVP_PKEY_asn1_set_public_check , +.Nm EVP_PKEY_asn1_set_param_check , +.Nm EVP_PKEY_asn1_set_security_bits .Nd manipulating and registering an EVP_PKEY_ASN1_METHOD structure .Sh SYNOPSIS .In openssl/evp.h @@ -132,6 +137,26 @@ .Fa "EVP_PKEY_ASN1_METHOD *ameth" .Fa "int (*pkey_ctrl)(EVP_PKEY *pkey, int op, long arg1, void *arg2)" .Fc +.Ft void +.Fo EVP_PKEY_asn1_set_check +.Fa "EVP_PKEY_ASN1_METHOD *ameth" +.Fa "int (*pkey_check)(const EVP_PKEY *pk)" +.Fc +.Ft void +.Fo EVP_PKEY_asn1_set_public_check +.Fa "EVP_PKEY_ASN1_METHOD *ameth" +.Fa "int (*pkey_public_check)(const EVP_PKEY *pk)" +.Fc +.Ft void +.Fo EVP_PKEY_asn1_set_param_check +.Fa "EVP_PKEY_ASN1_METHOD *ameth" +.Fa "int (*pkey_param_check)(const EVP_PKEY *pk)" +.Fc +.Ft void +.Fo EVP_PKEY_asn1_set_security_bits +.Fa "EVP_PKEY_ASN1_METHOD *ameth" +.Fa "int (*pkey_security_bits)(const EVP_PKEY *pkey)" +.Fc .Sh DESCRIPTION .Vt EVP_PKEY_ASN1_METHOD is a structure which holds a set of ASN.1 conversion, printing and @@ -325,6 +350,30 @@ This method is called by .Fn PKCS7_SIGNER_INFO_set , .Fn PKCS7_RECIP_INFO_set , and other functions. +.Bd -unfilled +.Ft int Fn (*pkey_check) "const EVP_PKEY *pk" +.Ft int Fn (*pkey_public_check) "const EVP_PKEY *pk" +.Ft int Fn (*pkey_param_check) "const EVP_PKEY *pk" +.Ed +.Pp +Check the validity of +.Fa pk +for key-pair, public component, and parameters, respectively. +These methods must return 0 for an invalid key or 1 for a valid key. +They are called by +.Xr EVP_PKEY_check 3 , +.Xr EVP_PKEY_public_check 3 , +and +.Xr EVP_PKEY_param_check 3 , +respectively. +.Bd -unfilled +.Ft int Fn (*pkey_security_bits) "const EVP_PKEY *pkey" +.Ed +.Pp +Return the security strength measured in bits of +.Fa pkey . +It is called by +.Xr EVP_PKEY_security_bits 3 . .Ss Functions .Fn EVP_PKEY_asn1_new creates and returns a new @@ -396,8 +445,12 @@ initializing the application. .Fn EVP_PKEY_asn1_set_private , .Fn EVP_PKEY_asn1_set_param , .Fn EVP_PKEY_asn1_set_free , +.Fn EVP_PKEY_asn1_set_ctrl , +.Fn EVP_PKEY_asn1_set_check , +.Fn EVP_PKEY_asn1_set_public_check , +.Fn EVP_PKEY_asn1_set_param_check , and -.Fn EVP_PKEY_asn1_set_ctrl +.Fn EVP_PKEY_asn1_set_security_bits set the diverse methods of the given .Vt EVP_PKEY_ASN1_METHOD object. @@ -418,6 +471,27 @@ return 0 on error or 1 on success. .Xr EVP_PKEY_new 3 , .Xr X509_PUBKEY_new 3 .Sh HISTORY -These functions first appeared in OpenSSL 1.0.0 -and have been available since +.Fn EVP_PKEY_asn1_new , +.Fn EVP_PKEY_asn1_copy , +.Fn EVP_PKEY_asn1_free , +.Fn EVP_PKEY_asn1_add0 , +.Fn EVP_PKEY_asn1_add_alias , +.Fn EVP_PKEY_asn1_set_public , +.Fn EVP_PKEY_asn1_set_private , +.Fn EVP_PKEY_asn1_set_param , +.Fn EVP_PKEY_asn1_set_free , +and +.Fn EVP_PKEY_asn1_set_ctrl +first appeared in OpenSSL 1.0.0 and have been available since .Ox 4.9 . +.Pp +.Fn EVP_PKEY_asn1_set_check , +.Fn EVP_PKEY_asn1_set_public_check , +and +.Fn EVP_PKEY_asn1_set_param_check +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.1 . +.Pp +.Fn EVP_PKEY_asn1_set_security_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.2 . diff --git a/lib/libcrypto/man/EVP_PKEY_check.3 b/lib/libcrypto/man/EVP_PKEY_check.3 new file mode 100644 index 00000000000..0d7688dd984 --- /dev/null +++ b/lib/libcrypto/man/EVP_PKEY_check.3 @@ -0,0 +1,149 @@ +.\" $OpenBSD: EVP_PKEY_check.3,v 1.1 2022/07/13 19:10:40 schwarze Exp $ +.\" +.\" Copyright (c) 2022 Ingo Schwarze +.\" +.\" 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. +.\" +.Dd $Mdocdate: July 13 2022 $ +.Dt EVP_PKEY_CHECK 3 +.Os +.Sh NAME +.Nm EVP_PKEY_check , +.Nm EVP_PKEY_public_check , +.Nm EVP_PKEY_param_check +.Nd key and parameter check functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fn EVP_PKEY_check "EVP_PKEY_CTX *ctx" +.Ft int +.Fn EVP_PKEY_public_check "EVP_PKEY_CTX *ctx" +.Ft int +.Fn EVP_PKEY_param_check "EVP_PKEY_CTX *ctx" +.Sh DESCRIPTION +.Fn EVP_PKEY_check +performs various sanity checks on the key contained in +.Fa ctx +but only supports a small number of key types by default. +It preferably uses the function +.Fa check +configured for +.Fa ctx +with +.Xr EVP_PKEY_meth_set_check 3 . +It falls back to the function +.Fa pkey_check +configured for the private key contained in +.Fa ctx +with +.Xr EVP_PKEY_asn1_set_check 3 . +If that wasn't configured either, it attempts to use the following +check functions: +.Pp +.Bl -tag -width 3n -compact -offset -indent +.It DH +not supported, return value \-2 +.It EC +.Xr EC_KEY_check_key 3 +.It RSA +.Xr RSA_check_key 3 +.El +.Pp +.Fn EVP_PKEY_public_check +performs various sanity checks on the public key contained in +.Fa ctx +but only supports a small number of key types by default. +It preferably uses the function +.Fa public_check +configured for +.Fa ctx +with +.Xr EVP_PKEY_meth_set_public_check 3 . +It falls back to the function +.Fa pkey_public_check +configured for the private key contained in +.Fa ctx +with +.Xr EVP_PKEY_asn1_set_public_check 3 . +If that wasn't configured either, it attempts to use the following +check functions: +.Pp +.Bl -tag -width 3n -compact -offset -indent +.It DH +.Xr DH_check_pub_key 3 +.It EC +.Xr EC_KEY_check_key 3 +.It RSA +not supported, return value \-2 +.El +.Pp +.Fn EVP_PKEY_param_check +performs various sanity checks on the key parameters contained in +.Fa ctx +but only supports a small number of key types by default. +It preferably uses the function +.Fa check +configured for +.Fa ctx +with +.Xr EVP_PKEY_meth_set_param_check 3 . +It falls back to the function +.Fa pkey_check +configured for the private key contained in +.Fa ctx +with +.Xr EVP_PKEY_asn1_set_param_check 3 . +If that wasn't configured either, it attempts to use the following +check functions: +.Pp +.Bl -tag -width 3n -compact -offset -indent +.It DH +.Xr DH_check 3 +.It EC +.Xr EC_GROUP_check 3 +.It RSA +not supported, return value \-2 +.El +.Sh RETURN VALUES +These functions return 1 if the check was performed and no problem +was found, 0 if a problem was found or if the check could not be +performed, for example because +.Fa ctx +does not contain an +.Vt EVP_PKEY +object, or \-2 if the required check function is neither configured for +.Fa ctx +nor for the +.Vt PKEY +contained therein, and the check in question is not supported by default +for the algorithm in question either. +.Sh SEE ALSO +.Xr DH_check 3 , +.Xr EC_GROUP_check 3 , +.Xr EC_KEY_new 3 , +.Xr EVP_PKEY_asn1_new 3 , +.Xr EVP_PKEY_CTX_new 3 , +.Xr EVP_PKEY_meth_new 3 , +.Xr EVP_PKEY_new 3 , +.Xr RSA_check_key 3 +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.1 +and have been available since +.Ox 7.1 . +.Sh BUGS +For EC keys, +.Fn EVP_PKEY_public_check +also checks the +.Em private +key and fails if there is a problem with any of the private +components, even if no problem is found with the public key. diff --git a/lib/libcrypto/man/EVP_PKEY_meth_new.3 b/lib/libcrypto/man/EVP_PKEY_meth_new.3 index 706824cd59c..3d9d1ba5be4 100644 --- a/lib/libcrypto/man/EVP_PKEY_meth_new.3 +++ b/lib/libcrypto/man/EVP_PKEY_meth_new.3 @@ -1,5 +1,5 @@ -.\" $OpenBSD: EVP_PKEY_meth_new.3,v 1.4 2019/06/06 01:06:58 schwarze Exp $ -.\" selective merge up to: OpenSSL 43f985fd Aug 21 11:47:17 2017 -0400 +.\" $OpenBSD: EVP_PKEY_meth_new.3,v 1.5 2022/07/13 19:10:40 schwarze Exp $ +.\" selective merge up to: OpenSSL 335a587b May 7 11:59:11 2019 +0200 .\" .\" This file was written by Paul Yang .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. @@ -48,7 +48,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: June 6 2019 $ +.Dd $Mdocdate: July 13 2022 $ .Dt EVP_PKEY_METH_NEW 3 .Os .Sh NAME @@ -70,7 +70,10 @@ .Nm EVP_PKEY_meth_set_encrypt , .Nm EVP_PKEY_meth_set_decrypt , .Nm EVP_PKEY_meth_set_derive , -.Nm EVP_PKEY_meth_set_ctrl +.Nm EVP_PKEY_meth_set_ctrl , +.Nm EVP_PKEY_meth_set_check , +.Nm EVP_PKEY_meth_set_public_check , +.Nm EVP_PKEY_meth_set_param_check .Nd manipulate an EVP_PKEY_METHOD structure .Sh SYNOPSIS .In openssl/evp.h @@ -184,6 +187,21 @@ .Fa "int (*ctrl)(EVP_PKEY_CTX *ctx, int type, int p1, void *p2)" .Fa "int (*ctrl_str)(EVP_PKEY_CTX *ctx, const char *type, const char *value)" .Fc +.Ft void +.Fo EVP_PKEY_meth_set_check +.Fa "EVP_PKEY_METHOD *pmeth" +.Fa "int (*check)(EVP_PKEY *pkey)" +.Fc +.Ft void +.Fo EVP_PKEY_meth_set_public_check +.Fa "EVP_PKEY_METHOD *pmeth" +.Fa "int (*public_check)(EVP_PKEY *pkey)" +.Fc +.Ft void +.Fo EVP_PKEY_meth_set_param_check +.Fa "EVP_PKEY_METHOD *pmeth" +.Fa "int (*param_check)(EVP_PKEY *pkey)" +.Fc .Sh DESCRIPTION The .Vt EVP_PKEY_METHOD @@ -451,6 +469,21 @@ methods are used to adjust algorithm-specific settings. See .Xr EVP_PKEY_CTX_ctrl 3 for details. +.Bd -unfilled +.Ft int Fn (*check) "EVP_PKEY *pkey" +.Ft int Fn (*public_check) "EVP_PKEY *pkey" +.Ft int Fn (*param_check) "EVP_PKEY *pkey" +.Ed +These methods are used to validate a key pair, the public component, +and the parameters for the given +.Fa pkey , +respectively. +They are called by +.Xr EVP_PKEY_check 3 , +.Xr EVP_PKEY_public_check 3 , +and +.Xr EVP_PKEY_param_check 3 , +respectively. .Ss Functions .Fn EVP_PKEY_meth_new creates a new @@ -553,3 +586,10 @@ first appeared in OpenSSL 1.0.0 and have been available since .Fn EVP_PKEY_meth_copy first appeared in OpenSSL 1.0.1 and has been available since .Ox 5.3 . +.Pp +.Fn EVP_PKEY_meth_set_check , +.Fn EVP_PKEY_meth_set_public_check , +and +.Fn EVP_PKEY_meth_set_param_check +first appeared in OpenSSL 1.1.1 and have been available since +.Ox 7.1 . diff --git a/lib/libcrypto/man/EVP_PKEY_size.3 b/lib/libcrypto/man/EVP_PKEY_size.3 new file mode 100644 index 00000000000..3070aee0179 --- /dev/null +++ b/lib/libcrypto/man/EVP_PKEY_size.3 @@ -0,0 +1,224 @@ +.\" $OpenBSD: EVP_PKEY_size.3,v 1.1 2022/07/13 19:10:40 schwarze Exp $ +.\" full merge up to: OpenSSL eed9d03b Jan 8 11:04:15 2020 +0100 +.\" +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2022 Ingo Schwarze +.\" +.\" 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 Richard Levitte . +.\" Copyright (c) 2020 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: July 13 2022 $ +.Dt EVP_PKEY_SIZE 3 +.Os +.Sh NAME +.Nm EVP_PKEY_size , +.Nm EVP_PKEY_bits , +.Nm EVP_PKEY_security_bits +.Nd EVP_PKEY information functions +.Sh SYNOPSIS +.In openssl/evp.h +.Ft int +.Fo EVP_PKEY_size +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_bits +.Fa "const EVP_PKEY *pkey" +.Fc +.Ft int +.Fo EVP_PKEY_security_bits +.Fa "const EVP_PKEY *pkey" +.Fc +.Sh DESCRIPTION +.Fn EVP_PKEY_size +returns the maximum size in bytes needed for the output buffer +for almost any operation that can be done with +.Fa pkey . +The primary use is with +.Xr EVP_SignFinal 3 +and +.Xr EVP_SealInit 3 . +The returned size is also large enough for the output buffer of +.Xr EVP_PKEY_sign 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_decrypt 3 , +and +.Xr EVP_PKEY_derive 3 . +.Pp +Unless the documentation for the operation says otherwise, +the size returned by +.Fn EVP_PKEY_size +is only an upper limit and the final content of the target +buffer may be smaller. +It is therefore crucial to take note of the size given back by the +function that performs the operation. +For example, +.Xr EVP_PKEY_sign 3 +returns that length in the +.Pf * Fa siglen +argument. +.Pp +Using +.Fn EVP_PKEY_size +is discouraged with +.Xr EVP_DigestSignFinal 3 . +.Pp +Most functions using an output buffer support passing +.Dv NULL +for the buffer and a pointer to an integer +to get the exact size that this function call delivers +in the context that it is called in. +This allows those functions to be called twice, once to find out the +exact buffer size, then allocate the buffer in between, and call that +function again to actually output the data. +For those functions, it isn't strictly necessary to call +.Fn EVP_PKEY_size +to find out the buffer size, but it may still be useful in cases +where it's desirable to know the upper limit in advance. +.Pp +By default, +.Fn EVP_PKEY_size +is supported for the following algorithms: +.Bl -column GOST01 "EVP_MAX_BLOCK_LENGTH = 32" +.It Ta same result as from: +.It CMAC Ta Dv EVP_MAX_BLOCK_LENGTH No = 32 +.It DH Ta Xr DH_size 3 +.It DSA Ta Xr DSA_size 3 +.It EC Ta Xr ECDSA_size 3 +.It GOST01 Ta 64 or 128 +.It HMAC Ta Dv EVP_MAX_MD_SIZE No = 64 +.It RSA Ta Xr RSA_size 3 +.El +.Pp +The application program can support additional algorithms by calling +.Xr EVP_PKEY_asn1_set_public 3 . +.Pp +.Fn EVP_PKEY_bits +returns the cryptographic length of the cryptosystem to which the key in +.Fa pkey +belongs, in bits. +The definition of cryptographic length is specific to the key cryptosystem. +By default, the following algorithms are supported: +.Bl -column GOST01 "the public domain parameter p" DSA_bits(3) +.It Ta cryptographic length = Ta same result as from: +.It Ta significant bits in ... Ta +.It DH Ta the public domain parameter Fa p Ta Xr DH_bits 3 +.It DSA Ta the public domain parameter Fa p Ta Xr DSA_bits 3 +.It EC Ta the order of the group Ta Xr EC_GROUP_order_bits 3 +.It GOST01 Ta 256 or 512 Ta \(em +.It RSA Ta the public modulus Ta Xr RSA_bits 3 +.El +.Pp +The application program can support additional algorithms by calling +.Xr EVP_PKEY_asn1_set_public 3 . +.Pp +.Fn EVP_PKEY_security_bits +returns the security strength measured in bits of the given +.Fa pkey +as defined in NIST SP800-57. +By default, the following algorithms are supported: +.Bl -column GOST01 DSA_security_bits(3) +.It Ta same result as from: +.It DH Ta Xr DH_security_bits 3 +.It DSA Ta Xr DSA_security_bits 3 +.It EC Ta Xr EC_GROUP_order_bits 3 divided by 2 +.It GOST01 Ta not supported, return value is \-2 +.It RSA Ta Xr RSA_security_bits 3 +.El +.Pp +For EC keys, if the result is greater than 80, it is rounded down +to 256, 192, 128, 112, or 80. +.Pp +The application program can support additional algorithms by calling +.Xr EVP_PKEY_asn1_set_security_bits 3 . +.Sh RETURN VALUES +.Fn EVP_PKEY_size +and +.Fn EVP_PKEY_bits +return a positive number or 0 if this size isn't available. +.Pp +.Fn EVP_PKEY_security_bits +returns a number in the range from 0 to 256 inclusive +or \-2 if this function is unsupported for the algorithm used by +.Fa pkey . +It returns 0 if +.Fa pkey +is +.Dv NULL . +.Sh SEE ALSO +.Xr EVP_PKEY_decrypt 3 , +.Xr EVP_PKEY_derive 3 , +.Xr EVP_PKEY_encrypt 3 , +.Xr EVP_PKEY_new 3 , +.Xr EVP_PKEY_sign 3 , +.Xr EVP_SealInit 3 , +.Xr EVP_SignFinal 3 +.Sh HISTORY +.Fn EVP_PKEY_size +first appeared in SSLeay 0.6.0 and +.Fn EVP_PKEY_bits +in SSLeay 0.9.0. +Both functions have been available since +.Ox 2.4 . +.Pp +.Fn EVP_PKEY_security_bits +first appeared in OpenSSL 1.1.0 and has been available since +.Ox 7.2 . diff --git a/lib/libcrypto/man/EVP_SignInit.3 b/lib/libcrypto/man/EVP_SignInit.3 index 06aeb2f141c..59dbca1e5b6 100644 --- a/lib/libcrypto/man/EVP_SignInit.3 +++ b/lib/libcrypto/man/EVP_SignInit.3 @@ -1,4 +1,4 @@ -.\" $OpenBSD: EVP_SignInit.3,v 1.15 2022/03/31 17:27:17 naddy Exp $ +.\" $OpenBSD: EVP_SignInit.3,v 1.16 2022/07/13 19:10:40 schwarze Exp $ .\" full merge up to: OpenSSL b97fdb57 Nov 11 09:33:09 2016 +0100 .\" selective merge up to: OpenSSL 79b49fb0 Mar 20 10:03:10 2018 +1000 .\" @@ -50,16 +50,14 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: March 31 2022 $ +.Dd $Mdocdate: July 13 2022 $ .Dt EVP_SIGNINIT 3 .Os .Sh NAME .Nm EVP_SignInit_ex , .Nm EVP_SignUpdate , .Nm EVP_SignFinal , -.Nm EVP_SignInit , -.Nm EVP_PKEY_size , -.Nm EVP_PKEY_bits +.Nm EVP_SignInit .Nd EVP signing functions .Sh SYNOPSIS .In openssl/evp.h @@ -87,14 +85,6 @@ .Fa "EVP_MD_CTX *ctx" .Fa "const EVP_MD *type" .Fc -.Ft int -.Fo EVP_PKEY_size -.Fa "const EVP_PKEY *pkey" -.Fc -.Ft int -.Fo EVP_PKEY_bits -.Fa "const EVP_PKEY *pkey" -.Fc .Sh DESCRIPTION The EVP signature routines are a high level interface to digital signatures. @@ -132,7 +122,7 @@ and places the signature in .Fa sig . .Fa sig must be at least -.Fn EVP_PKEY_size pkey +.Xr EVP_PKEY_size 3 bytes in size. .Fa s is an OUT parameter, and not used as an IN parameter. @@ -140,7 +130,7 @@ The number of bytes of data written (i.e.\& the length of the signature) will be written to the integer at .Fa s . At most -.Fn EVP_PKEY_size pkey +.Xr EVP_PKEY_size 3 bytes will be written. .Pp .Fn EVP_SignInit @@ -149,12 +139,6 @@ initializes a signing context to use the default implementation of digest .Fa type . .Pp -.Fn EVP_PKEY_size -returns the maximum size of a signature in bytes. -The actual signature returned by -.Fn EVP_SignFinal -may be smaller. -.Pp The EVP interface to digital signatures should almost always be used in preference to the low level interfaces. This is because the code then becomes transparent to the algorithm used @@ -180,31 +164,20 @@ and .Fn EVP_SignFinal return 1 for success and 0 for failure. .Pp -.Fn EVP_PKEY_size -returns the maximum size of a signature in bytes. -.Pp -.Fn EVP_PKEY_bits -returns the number of significant bits in the key -or 0 if an error occurs. -.Pp The error codes can be obtained by .Xr ERR_get_error 3 . .Sh SEE ALSO .Xr evp 3 , .Xr EVP_DigestInit 3 , .Xr EVP_PKEY_asn1_set_public 3 , +.Xr EVP_PKEY_size 3 , .Xr EVP_VerifyInit 3 .Sh HISTORY .Fn EVP_SignInit , .Fn EVP_SignUpdate , and .Fn EVP_SignFinal -first appeared in SSLeay 0.5.1. -.Fn EVP_PKEY_size -first appeared in SSLeay 0.6.0. -.Fn EVP_PKEY_bits -first appeared in SSLeay 0.9.0. -These functions have been available since +first appeared in SSLeay 0.5.1 and have been available since .Ox 2.4 . .Pp .Fn EVP_SignInit_ex -- 2.20.1