1 files changed, 76 insertions, 0 deletions

diff --git a/src/lib/libcrypto/man/BN_num_bytes.3 b/src/lib/libcrypto/man/BN_num_bytes.3
new file mode 100644
index 0000000000..2d7be7e443
--- /dev/null
+++ b/src/lib/libcrypto/man/BN_num_bytes.3
@@ -0,0 +1,76 @@
+.Dd $Mdocdate: February 23 2015 $
+.Dt BN_NUM_BYTES 3
+.Os
+.Sh NAME
+.Nm BN_num_bits ,
+.Nm BN_num_bytes ,
+.Nm BN_num_bits_word
+.Nd get BIGNUM size
+.Sh SYNOPSIS
+.In openssl/bn.h
+.Ft int
+.Fo BN_num_bytes
+.Fa "const BIGNUM *a"
+.Fc
+.Ft int
+.Fo BN_num_bits
+.Fa "const BIGNUM *a"
+.Fc
+.Ft int
+.Fo BN_num_bits_word
+.Fa "BN_ULONG w"
+.Fc
+.Sh DESCRIPTION
+.Fn BN_num_bytes
+returns the size of a
+.Sy BIGNUM
+in bytes.
+.Pp
+.Fn BN_num_bits_word
+returns the number of significant bits in a word.
+If we take 0x00000432 as an example, it returns 11, not 16, not 32.
+Basically, except for a zero, it returns
+.Pp
+.D1 floor(log2( Ns Fa w ) ) No + 1 .
+.Pp
+.Fn BN_num_bits
+returns the number of significant bits in a
+.Sy BIGNUM ,
+following the same principle as
+.Fn BN_num_bits_word .
+.Pp
+.Fn BN_num_bytes
+is a macro.
+.Sh RETURN VALUES
+The size.
+.Sh NOTES
+Some have tried using
+.Fn BN_num_bits
+on individual numbers in RSA keys, DH keys and DSA keys, and found that
+they don't always come up with the number of bits they expected
+(something like 512, 1024, 2048, ...). This is because generating a
+number with some specific number of bits doesn't always set the highest
+bits, thereby making the number of
+.Em significant
+bits a little lower.
+If you want to know the "key size" of such a key, either use functions
+like
+.Xr RSA_size 3 ,
+.Xr DH_size 3 ,
+and
+.Xr DSA_size 3 ,
+or use
+.Fn BN_num_bytes
+and multiply with 8 (although there's no real guarantee that will match
+the "key size", just a lot more probability).
+.Sh SEE ALSO
+.Xr bn 3 ,
+.Xr DH_size 3 ,
+.Xr DSA_size 3 ,
+.Xr RSA_size 3
+.Sh HISTORY
+.Fn BN_num_bytes ,
+.Fn BN_num_bits ,
+and
+.Fn BN_num_bits_word
+are available in all versions of SSLeay and OpenSSL.