From 8e2ec202c6914d3979c1c4579a278c6ffe4257d0 Mon Sep 17 00:00:00 2001 From: schwarze Date: Wed, 13 Jul 2022 17:32:16 +0000 Subject: [PATCH] New manual page written from scratch; tb@ recently added these functions to libcrypto and also provided feedback on my first draft of this page. --- lib/libcrypto/man/RSA_security_bits.3 | 137 ++++++++++++++++++++++++++ 1 file changed, 137 insertions(+) create mode 100644 lib/libcrypto/man/RSA_security_bits.3 diff --git a/lib/libcrypto/man/RSA_security_bits.3 b/lib/libcrypto/man/RSA_security_bits.3 new file mode 100644 index 00000000000..f7024a79560 --- /dev/null +++ b/lib/libcrypto/man/RSA_security_bits.3 @@ -0,0 +1,137 @@ +.\" $OpenBSD: RSA_security_bits.3,v 1.1 2022/07/13 17:32:16 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 RSA_SECURITY_BITS 3 +.Os +.Sh NAME +.Nm RSA_security_bits , +.Nm DSA_security_bits , +.Nm DH_security_bits , +.Nm BN_security_bits +.Nd get security strength +.Sh SYNOPSIS +.In openssl/rsa.h +.Ft int +.Fn RSA_security_bits "const RSA *rsa" +.In openssl/dsa.h +.Ft int +.Fn DSA_security_bits "const DSA *dsa" +.In openssl/dh.h +.Ft int +.Fn DH_security_bits "const DH *dh" +.In openssl/bn.h +.Ft int +.Fo BN_security_bits +.Fa "int pubbits" +.Fa "int privbits" +.Fc +.Sh DESCRIPTION +These functions return the security strength of some specific types of +cryptographic keys, measured in bits. +It is approximately the binary logarithm of the number of operations +an attacker has to perform in order to break the key. +.Pp +.Fn RSA_security_bits +uses only the number of significant bits in the public modulus of +.Fa rsa +as returned by +.Xr RSA_bits 3 . +It returns +.Bl -column 256 for 15360 last_column -offset indent +.It 256 Ta for Ta 15360 Ta or more significant bits +.It 192 Ta Ta 7680 Ta +.It 128 Ta Ta 3072 Ta +.It 112 Ta Ta 2048 Ta +.It 80 Ta Ta 1024 Ta +.El +.Pp +or 0 otherwise. +.Pp +.Fn DSA_security_bits +uses the number of significant bits in the public domain parameter +.Fa p +contained in the +.Fa dsa +object, which is equal to the size of the public key, in the same way as +.Fn RSA_security_bits . +In addition, the public domain parameter +.Fa q +contained in the +.Fa dsa +object, which is equal to the size of the private key, is inspected. +The return value is either the security strength according to the above table +or half the size of the private key, whichever is smaller. +If the return value would be smaller than 80, 0 is returned instead. +.Pp +.Fn DH_security_bits +uses the number of significant bits in the shared secret contained in the +.Fa dh +object as returned by +.Xr DH_bits 3 +in the same way as +.Fn RSA_security_bits . +If +.Fa dh +contains the domain parameter +.Fa q , +its number of significant bits is used in the same way as for +.Fn DSA_security_bits +to limit the return value. +Otherwise, if +.Fa dh +contains the length of the secret exponent in bits, +that number is used. +If neither is available, only the above table is used +without calculating a minimum. +.Pp +.Fn BN_security_bits +is a combined function. +If \-1 is passed for the +.Fa privbits +argument, it behaves like +.Fn RSA_security_bits . +Otherwise, it behaves like +.Fn DSA_security_bits . +.Sh RETURN VALUES +All these functions return numbers in the range from 0 to 256 inclusive. +.Pp +.Fn DSA_security_bits +fails and returns \-1 unless both of the +.Fa p +and +.Fa q +domain parameters are present. +.Sh SEE ALSO +.Xr BN_num_bits 3 , +.Xr DH_bits 3 , +.Xr DH_get0_pqg 3 , +.Xr DSA_get0_pqg 3 , +.Xr RSA_bits 3 , +.Xr SSL_CTX_set_security_level 3 +.Rs +.%A Elaine Barker +.%T Recommendation for Key Management +.%I U.S. National Institute of Standards and Technology +.%R NIST Special Publication 800-57 Part 1 Revision 5 +.%U https://doi.org/10.6028/NIST.SP.800-57pt1r5 +.%C Gaithersburg, MD +.%D May 2020 +.Re +.Sh HISTORY +These functions first appeared in OpenSSL 1.1.0 +and have been available since +.Ox 7.2 . -- 2.20.1