xref: /openbsd-src/lib/libcrypto/man/BN_num_bytes.3 (revision 3a9f61673cd8d1f849efda71dca513ff39c0523c)
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