1.\" $OpenBSD: BN_num_bytes.3,v 1.9 2022/11/22 18:55:04 schwarze Exp $ 2.\" full merge up to: OpenSSL 9e183d22 Mar 11 08:56:44 2017 -0500 3.\" 4.\" This file is a derived work. 5.\" The changes are covered by the following Copyright and license: 6.\" 7.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 8.\" 9.\" Permission to use, copy, modify, and distribute this software for any 10.\" purpose with or without fee is hereby granted, provided that the above 11.\" copyright notice and this permission notice appear in all copies. 12.\" 13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20.\" 21.\" The original file was written by Ulf Moeller <ulf@openssl.org> 22.\" and Richard Levitte <levitte@openssl.org>. 23.\" Copyright (c) 2000, 2004 The OpenSSL Project. All rights reserved. 24.\" 25.\" Redistribution and use in source and binary forms, with or without 26.\" modification, are permitted provided that the following conditions 27.\" are met: 28.\" 29.\" 1. Redistributions of source code must retain the above copyright 30.\" notice, this list of conditions and the following disclaimer. 31.\" 32.\" 2. Redistributions in binary form must reproduce the above copyright 33.\" notice, this list of conditions and the following disclaimer in 34.\" the documentation and/or other materials provided with the 35.\" distribution. 36.\" 37.\" 3. All advertising materials mentioning features or use of this 38.\" software must display the following acknowledgment: 39.\" "This product includes software developed by the OpenSSL Project 40.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 41.\" 42.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 43.\" endorse or promote products derived from this software without 44.\" prior written permission. For written permission, please contact 45.\" openssl-core@openssl.org. 46.\" 47.\" 5. Products derived from this software may not be called "OpenSSL" 48.\" nor may "OpenSSL" appear in their names without prior written 49.\" permission of the OpenSSL Project. 50.\" 51.\" 6. Redistributions of any form whatsoever must retain the following 52.\" acknowledgment: 53.\" "This product includes software developed by the OpenSSL Project 54.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 55.\" 56.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 57.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 58.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 59.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 60.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 61.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 62.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 63.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 64.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 65.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 66.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 67.\" OF THE POSSIBILITY OF SUCH DAMAGE. 68.\" 69.Dd $Mdocdate: November 22 2022 $ 70.Dt BN_NUM_BYTES 3 71.Os 72.Sh NAME 73.Nm BN_num_bits_word , 74.Nm BN_num_bits , 75.Nm BN_num_bytes 76.Nd get BIGNUM size 77.Sh SYNOPSIS 78.In openssl/bn.h 79.Ft int 80.Fo BN_num_bits_word 81.Fa "BN_ULONG w" 82.Fc 83.Ft int 84.Fo BN_num_bits 85.Fa "const BIGNUM *a" 86.Fc 87.Ft int 88.Fo BN_num_bytes 89.Fa "const BIGNUM *a" 90.Fc 91.Sh DESCRIPTION 92.Fn BN_num_bits_word 93returns the number of significant bits in 94.Fa w , 95that is, the minimum number of digits needed to write 96.Fa w 97as a binary number. 98Except for an argument of 0, this is 99.Pp 100.D1 floor(log2( Ns Fa w ) ) No + 1 . 101.Pp 102.Vt BN_ULONG 103is a macro that expands to 104.Vt unsigned long Pq = Vt uint64_t 105on 106.Dv _LP64 107platforms and 108.Vt unsigned int Pq = Vt uint32_t 109elsewhere. 110.Pp 111.Fn BN_num_bits 112returns the number of significant bits in the value of the 113.Fa "BIGNUM *a" , 114following the same principle as 115.Fn BN_num_bits_word . 116.Pp 117.Fn BN_num_bytes 118is a macro that returns the number of significant bytes in 119.Fa a , 120i.e. the minimum number of bytes needed to store the value of 121.Fa a , 122that is, 123.Fn BN_num_bits a 124divided by eight and rounded up to the next integer number. 125.Sh RETURN VALUES 126.Fn BN_num_bits_word 127returns the number of significant bits in 128.Fa w 129or 0 if 130.Fa w 131is 0. 132The maximum return value that can occur is 133.Dv BN_BITS2 , 134which is 64 on 135.Dv _LP64 136platforms and 32 elsewhere. 137.Pp 138.Fn BN_num_bits 139returns the number of significant bits and 140.Fn BN_num_bytes 141the number of significant bytes in 142.Fa a , 143or 0 if the value of 144.Fa a 145is 0. 146.Sh SEE ALSO 147.Xr BN_new 3 , 148.Xr BN_security_bits 3 , 149.Xr DH_size 3 , 150.Xr DSA_size 3 , 151.Xr RSA_size 3 152.Sh HISTORY 153.Fn BN_num_bytes 154and 155.Fn BN_num_bits 156first appeared in SSLeay 0.5.1. 157.Fn BN_num_bits_word 158first appeared in SSLeay 0.5.2. 159These functions have been available since 160.Ox 2.4 . 161.Sh CAVEATS 162Some have tried using 163.Fn BN_num_bits 164on individual numbers in RSA keys, DH keys and DSA keys, and found that 165they don't always come up with the number of bits they expected 166(something like 512, 1024, 2048, ...). 167This is because generating a number with some specific number of bits 168doesn't always set the highest bits, thereby making the number of 169.Em significant 170bits a little smaller. 171If you want to know the "key size" of such a key, use functions like 172.Xr RSA_size 3 , 173.Xr DH_size 3 , 174and 175.Xr DSA_size 3 . 176