1.\" $OpenBSD: RSA_security_bits.3,v 1.1 2022/07/13 17:32:16 schwarze Exp $ 2.\" 3.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: July 13 2022 $ 18.Dt RSA_SECURITY_BITS 3 19.Os 20.Sh NAME 21.Nm RSA_security_bits , 22.Nm DSA_security_bits , 23.Nm DH_security_bits , 24.Nm BN_security_bits 25.Nd get security strength 26.Sh SYNOPSIS 27.In openssl/rsa.h 28.Ft int 29.Fn RSA_security_bits "const RSA *rsa" 30.In openssl/dsa.h 31.Ft int 32.Fn DSA_security_bits "const DSA *dsa" 33.In openssl/dh.h 34.Ft int 35.Fn DH_security_bits "const DH *dh" 36.In openssl/bn.h 37.Ft int 38.Fo BN_security_bits 39.Fa "int pubbits" 40.Fa "int privbits" 41.Fc 42.Sh DESCRIPTION 43These functions return the security strength of some specific types of 44cryptographic keys, measured in bits. 45It is approximately the binary logarithm of the number of operations 46an attacker has to perform in order to break the key. 47.Pp 48.Fn RSA_security_bits 49uses only the number of significant bits in the public modulus of 50.Fa rsa 51as returned by 52.Xr RSA_bits 3 . 53It returns 54.Bl -column 256 for 15360 last_column -offset indent 55.It 256 Ta for Ta 15360 Ta or more significant bits 56.It 192 Ta Ta 7680 Ta 57.It 128 Ta Ta 3072 Ta 58.It 112 Ta Ta 2048 Ta 59.It 80 Ta Ta 1024 Ta 60.El 61.Pp 62or 0 otherwise. 63.Pp 64.Fn DSA_security_bits 65uses the number of significant bits in the public domain parameter 66.Fa p 67contained in the 68.Fa dsa 69object, which is equal to the size of the public key, in the same way as 70.Fn RSA_security_bits . 71In addition, the public domain parameter 72.Fa q 73contained in the 74.Fa dsa 75object, which is equal to the size of the private key, is inspected. 76The return value is either the security strength according to the above table 77or half the size of the private key, whichever is smaller. 78If the return value would be smaller than 80, 0 is returned instead. 79.Pp 80.Fn DH_security_bits 81uses the number of significant bits in the shared secret contained in the 82.Fa dh 83object as returned by 84.Xr DH_bits 3 85in the same way as 86.Fn RSA_security_bits . 87If 88.Fa dh 89contains the domain parameter 90.Fa q , 91its number of significant bits is used in the same way as for 92.Fn DSA_security_bits 93to limit the return value. 94Otherwise, if 95.Fa dh 96contains the length of the secret exponent in bits, 97that number is used. 98If neither is available, only the above table is used 99without calculating a minimum. 100.Pp 101.Fn BN_security_bits 102is a combined function. 103If \-1 is passed for the 104.Fa privbits 105argument, it behaves like 106.Fn RSA_security_bits . 107Otherwise, it behaves like 108.Fn DSA_security_bits . 109.Sh RETURN VALUES 110All these functions return numbers in the range from 0 to 256 inclusive. 111.Pp 112.Fn DSA_security_bits 113fails and returns \-1 unless both of the 114.Fa p 115and 116.Fa q 117domain parameters are present. 118.Sh SEE ALSO 119.Xr BN_num_bits 3 , 120.Xr DH_bits 3 , 121.Xr DH_get0_pqg 3 , 122.Xr DSA_get0_pqg 3 , 123.Xr RSA_bits 3 , 124.Xr SSL_CTX_set_security_level 3 125.Rs 126.%A Elaine Barker 127.%T Recommendation for Key Management 128.%I U.S. National Institute of Standards and Technology 129.%R NIST Special Publication 800-57 Part 1 Revision 5 130.%U https://doi.org/10.6028/NIST.SP.800-57pt1r5 131.%C Gaithersburg, MD 132.%D May 2020 133.Re 134.Sh HISTORY 135These functions first appeared in OpenSSL 1.1.0 136and have been available since 137.Ox 7.2 . 138