1*3a9f6167Sschwarze.\" $OpenBSD: BN_num_bytes.3,v 1.9 2022/11/22 18:55:04 schwarze Exp $ 2*3a9f6167Sschwarze.\" full merge up to: OpenSSL 9e183d22 Mar 11 08:56:44 2017 -0500 38974101aSjmc.\" 4*3a9f6167Sschwarze.\" This file is a derived work. 5*3a9f6167Sschwarze.\" The changes are covered by the following Copyright and license: 6*3a9f6167Sschwarze.\" 7*3a9f6167Sschwarze.\" Copyright (c) 2022 Ingo Schwarze <schwarze@openbsd.org> 8*3a9f6167Sschwarze.\" 9*3a9f6167Sschwarze.\" Permission to use, copy, modify, and distribute this software for any 10*3a9f6167Sschwarze.\" purpose with or without fee is hereby granted, provided that the above 11*3a9f6167Sschwarze.\" copyright notice and this permission notice appear in all copies. 12*3a9f6167Sschwarze.\" 13*3a9f6167Sschwarze.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 14*3a9f6167Sschwarze.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 15*3a9f6167Sschwarze.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 16*3a9f6167Sschwarze.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 17*3a9f6167Sschwarze.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 18*3a9f6167Sschwarze.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 19*3a9f6167Sschwarze.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 20*3a9f6167Sschwarze.\" 21*3a9f6167Sschwarze.\" The original file was written by Ulf Moeller <ulf@openssl.org> 2288c50c74Sschwarze.\" and Richard Levitte <levitte@openssl.org>. 2388c50c74Sschwarze.\" Copyright (c) 2000, 2004 The OpenSSL Project. All rights reserved. 2488c50c74Sschwarze.\" 2588c50c74Sschwarze.\" Redistribution and use in source and binary forms, with or without 2688c50c74Sschwarze.\" modification, are permitted provided that the following conditions 2788c50c74Sschwarze.\" are met: 2888c50c74Sschwarze.\" 2988c50c74Sschwarze.\" 1. Redistributions of source code must retain the above copyright 3088c50c74Sschwarze.\" notice, this list of conditions and the following disclaimer. 3188c50c74Sschwarze.\" 3288c50c74Sschwarze.\" 2. Redistributions in binary form must reproduce the above copyright 3388c50c74Sschwarze.\" notice, this list of conditions and the following disclaimer in 3488c50c74Sschwarze.\" the documentation and/or other materials provided with the 3588c50c74Sschwarze.\" distribution. 3688c50c74Sschwarze.\" 3788c50c74Sschwarze.\" 3. All advertising materials mentioning features or use of this 3888c50c74Sschwarze.\" software must display the following acknowledgment: 3988c50c74Sschwarze.\" "This product includes software developed by the OpenSSL Project 4088c50c74Sschwarze.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 4188c50c74Sschwarze.\" 4288c50c74Sschwarze.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 4388c50c74Sschwarze.\" endorse or promote products derived from this software without 4488c50c74Sschwarze.\" prior written permission. For written permission, please contact 4588c50c74Sschwarze.\" openssl-core@openssl.org. 4688c50c74Sschwarze.\" 4788c50c74Sschwarze.\" 5. Products derived from this software may not be called "OpenSSL" 4888c50c74Sschwarze.\" nor may "OpenSSL" appear in their names without prior written 4988c50c74Sschwarze.\" permission of the OpenSSL Project. 5088c50c74Sschwarze.\" 5188c50c74Sschwarze.\" 6. Redistributions of any form whatsoever must retain the following 5288c50c74Sschwarze.\" acknowledgment: 5388c50c74Sschwarze.\" "This product includes software developed by the OpenSSL Project 5488c50c74Sschwarze.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 5588c50c74Sschwarze.\" 5688c50c74Sschwarze.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 5788c50c74Sschwarze.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 5888c50c74Sschwarze.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 5988c50c74Sschwarze.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 6088c50c74Sschwarze.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 6188c50c74Sschwarze.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 6288c50c74Sschwarze.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 6388c50c74Sschwarze.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 6488c50c74Sschwarze.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 6588c50c74Sschwarze.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 6688c50c74Sschwarze.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 6788c50c74Sschwarze.\" OF THE POSSIBILITY OF SUCH DAMAGE. 6888c50c74Sschwarze.\" 69*3a9f6167Sschwarze.Dd $Mdocdate: November 22 2022 $ 70f1048625Sschwarze.Dt BN_NUM_BYTES 3 71f1048625Sschwarze.Os 72f1048625Sschwarze.Sh NAME 73*3a9f6167Sschwarze.Nm BN_num_bits_word , 74c60befd1Sjmc.Nm BN_num_bits , 75*3a9f6167Sschwarze.Nm BN_num_bytes 76f1048625Sschwarze.Nd get BIGNUM size 77f1048625Sschwarze.Sh SYNOPSIS 78f1048625Sschwarze.In openssl/bn.h 79f1048625Sschwarze.Ft int 80*3a9f6167Sschwarze.Fo BN_num_bits_word 81*3a9f6167Sschwarze.Fa "BN_ULONG w" 82f1048625Sschwarze.Fc 83f1048625Sschwarze.Ft int 84f1048625Sschwarze.Fo BN_num_bits 85f1048625Sschwarze.Fa "const BIGNUM *a" 86f1048625Sschwarze.Fc 87f1048625Sschwarze.Ft int 88*3a9f6167Sschwarze.Fo BN_num_bytes 89*3a9f6167Sschwarze.Fa "const BIGNUM *a" 90f1048625Sschwarze.Fc 91f1048625Sschwarze.Sh DESCRIPTION 92f1048625Sschwarze.Fn BN_num_bits_word 93*3a9f6167Sschwarzereturns the number of significant bits in 94*3a9f6167Sschwarze.Fa w , 95*3a9f6167Sschwarzethat is, the minimum number of digits needed to write 96*3a9f6167Sschwarze.Fa w 97*3a9f6167Sschwarzeas a binary number. 98*3a9f6167SschwarzeExcept for an argument of 0, this is 99f1048625Sschwarze.Pp 100f1048625Sschwarze.D1 floor(log2( Ns Fa w ) ) No + 1 . 101f1048625Sschwarze.Pp 102*3a9f6167Sschwarze.Vt BN_ULONG 103*3a9f6167Sschwarzeis a macro that expands to 104*3a9f6167Sschwarze.Vt unsigned long Pq = Vt uint64_t 105*3a9f6167Sschwarzeon 106*3a9f6167Sschwarze.Dv _LP64 107*3a9f6167Sschwarzeplatforms and 108*3a9f6167Sschwarze.Vt unsigned int Pq = Vt uint32_t 109*3a9f6167Sschwarzeelsewhere. 110*3a9f6167Sschwarze.Pp 111f1048625Sschwarze.Fn BN_num_bits 112*3a9f6167Sschwarzereturns the number of significant bits in the value of the 113*3a9f6167Sschwarze.Fa "BIGNUM *a" , 114f1048625Sschwarzefollowing the same principle as 115f1048625Sschwarze.Fn BN_num_bits_word . 116f1048625Sschwarze.Pp 117f1048625Sschwarze.Fn BN_num_bytes 118*3a9f6167Sschwarzeis a macro that returns the number of significant bytes in 119*3a9f6167Sschwarze.Fa a , 120*3a9f6167Sschwarzei.e. the minimum number of bytes needed to store the value of 121*3a9f6167Sschwarze.Fa a , 122*3a9f6167Sschwarzethat is, 123*3a9f6167Sschwarze.Fn BN_num_bits a 124*3a9f6167Sschwarzedivided by eight and rounded up to the next integer number. 125c60befd1Sjmc.Sh RETURN VALUES 126*3a9f6167Sschwarze.Fn BN_num_bits_word 127*3a9f6167Sschwarzereturns the number of significant bits in 128*3a9f6167Sschwarze.Fa w 129*3a9f6167Sschwarzeor 0 if 130*3a9f6167Sschwarze.Fa w 131*3a9f6167Sschwarzeis 0. 132*3a9f6167SschwarzeThe maximum return value that can occur is 133*3a9f6167Sschwarze.Dv BN_BITS2 , 134*3a9f6167Sschwarzewhich is 64 on 135*3a9f6167Sschwarze.Dv _LP64 136*3a9f6167Sschwarzeplatforms and 32 elsewhere. 137*3a9f6167Sschwarze.Pp 138*3a9f6167Sschwarze.Fn BN_num_bits 139*3a9f6167Sschwarzereturns the number of significant bits and 140*3a9f6167Sschwarze.Fn BN_num_bytes 141*3a9f6167Sschwarzethe number of significant bytes in 142*3a9f6167Sschwarze.Fa a , 143*3a9f6167Sschwarzeor 0 if the value of 144*3a9f6167Sschwarze.Fa a 145*3a9f6167Sschwarzeis 0. 146f1048625Sschwarze.Sh SEE ALSO 14768d7c31cSschwarze.Xr BN_new 3 , 148dd550453Sschwarze.Xr BN_security_bits 3 , 149f1048625Sschwarze.Xr DH_size 3 , 150f1048625Sschwarze.Xr DSA_size 3 , 151f1048625Sschwarze.Xr RSA_size 3 152f1048625Sschwarze.Sh HISTORY 15310e00d17Sschwarze.Fn BN_num_bytes 15410e00d17Sschwarzeand 15510e00d17Sschwarze.Fn BN_num_bits 15610e00d17Sschwarzefirst appeared in SSLeay 0.5.1. 15710e00d17Sschwarze.Fn BN_num_bits_word 15810e00d17Sschwarzefirst appeared in SSLeay 0.5.2. 15910e00d17SschwarzeThese functions have been available since 1600c85fcf7Sschwarze.Ox 2.4 . 161*3a9f6167Sschwarze.Sh CAVEATS 162*3a9f6167SschwarzeSome have tried using 163*3a9f6167Sschwarze.Fn BN_num_bits 164*3a9f6167Sschwarzeon individual numbers in RSA keys, DH keys and DSA keys, and found that 165*3a9f6167Sschwarzethey don't always come up with the number of bits they expected 166*3a9f6167Sschwarze(something like 512, 1024, 2048, ...). 167*3a9f6167SschwarzeThis is because generating a number with some specific number of bits 168*3a9f6167Sschwarzedoesn't always set the highest bits, thereby making the number of 169*3a9f6167Sschwarze.Em significant 170*3a9f6167Sschwarzebits a little smaller. 171*3a9f6167SschwarzeIf you want to know the "key size" of such a key, use functions like 172*3a9f6167Sschwarze.Xr RSA_size 3 , 173*3a9f6167Sschwarze.Xr DH_size 3 , 174*3a9f6167Sschwarzeand 175*3a9f6167Sschwarze.Xr DSA_size 3 . 176