Merge documentation for BN_bn2binpad(3), BN_bn2lebinpad(3),

and BN_lebin2bn(3) from the OpenSSL 1.1.1 branch,
which is still under a free license.
While here, tweak a number of details for clarity.
OK tb@

1 files changed, 77 insertions, 13 deletions

diff --git a/src/lib/libcrypto/man/BN_bn2bin.3 b/src/lib/libcrypto/man/BN_bn2bin.3
index 9569d111b5..48d350ab48 100644
--- a/src/lib/libcrypto/man/BN_bn2bin.3
+++ b/src/lib/libcrypto/man/BN_bn2bin.3
@@ -1,8 +1,8 @@
-.\"     $OpenBSD: BN_bn2bin.3,v 1.13 2019/06/10 14:58:48 schwarze Exp $
-.\" full merge up to: OpenSSL a528d4f0 Oct 27 13:40:11 2015 -0400
-.\" selective merge up to: OpenSSL 1212818e Sep 11 13:22:14 2018 +0100
+.\" $OpenBSD: BN_bn2bin.3,v 1.14 2021/09/11 08:45:47 schwarze Exp $
+.\" full merge up to: OpenSSL 24a535ea Sep 22 13:14:20 2020 +0100
 .\"
-.\" This file was written by Ulf Moeller <ulf@openssl.org>.
+.\" This file was written by Ulf Moeller <ulf@openssl.org>
+.\" and Dr. Stephen Henson <steve@openssl.org>.
 .\" Copyright (c) 2000, 2002, 2016 The OpenSSL Project.  All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,12 +49,15 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 10 2019 $
+.Dd $Mdocdate: September 11 2021 $
 .Dt BN_BN2BIN 3
 .Os
 .Sh NAME
 .Nm BN_bn2bin ,
+.Nm BN_bn2binpad ,
 .Nm BN_bin2bn ,
+.Nm BN_bn2lebinpad ,
+.Nm BN_lebin2bn ,
 .Nm BN_bn2hex ,
 .Nm BN_bn2dec ,
 .Nm BN_hex2bn ,
@@ -72,12 +75,30 @@
 .Fa "const BIGNUM *a"
 .Fa "unsigned char *to"
 .Fc
+.Ft int
+.Fo BN_bn2binpad
+.Fa "const BIGNUM *a"
+.Fa "unsigned char *to"
+.Fa "int tolen"
+.Fc
 .Ft BIGNUM *
 .Fo BN_bin2bn
 .Fa "const unsigned char *s"
 .Fa "int len"
 .Fa "BIGNUM *ret"
 .Fc
+.Ft int
+.Fo BN_bn2lebinpad
+.Fa "const BIGNUM *a"
+.Fa "unsigned char *to"
+.Fa "int tolen"
+.Fc
+.Ft BIGNUM *
+.Fo BN_lebin2bn
+.Fa "const unsigned char *s"
+.Fa "int len"
+.Fa "BIGNUM *ret"
+.Fc
 .Ft char *
 .Fo BN_bn2hex
 .Fa "const BIGNUM *a"
@@ -88,17 +109,17 @@
 .Fc
 .Ft int
 .Fo BN_hex2bn
-.Fa "BIGNUM **a"
+.Fa "BIGNUM **ap"
 .Fa "const char *str"
 .Fc
 .Ft int
 .Fo BN_dec2bn
-.Fa "BIGNUM **a"
+.Fa "BIGNUM **ap"
 .Fa "const char *str"
 .Fc
 .Ft int
 .Fo BN_asc2bn
-.Fa "BIGNUM **a"
+.Fa "BIGNUM **ap"
 .Fa "const char *str"
 .Fc
 .Ft int
@@ -133,6 +154,21 @@ must point to
 .Fn BN_num_bytes a
 bytes of memory.
 .Pp
+.Fn BN_bn2binpad
+also converts the absolute value of
+.Fa a
+into big-endian form and stores it at
+.Fa to .
+.Fa tolen
+indicates the length of the output buffer
+.Pf * Fa to .
+The result is padded with zeros if necessary.
+If
+.Fa tolen
+is less than
+.Fn BN_num_bytes a ,
+an error is returned.
+.Pp
 .Fn BN_bin2bn
 converts the positive integer in big-endian form of length
 .Fa len
@@ -150,6 +186,17 @@ a new
 .Vt BIGNUM
 is created.
 .Pp
+.Fn BN_bn2lebinpad
+and
+.Fn BN_lebin2bn
+are identical to
+.Fn BN_bn2binpad
+and
+.Fn BN_bin2bn
+except the buffer
+.Pf * Fa to
+is in little-endian format.
+.Pp
 .Fn BN_bn2hex
 and
 .Fn BN_bn2dec
@@ -170,16 +217,16 @@ Conversion stops at the first byte that is not a hexadecimal digit.
 The number is converted to a
 .Vt BIGNUM
 and stored in
-.Pf * Fa a .
+.Pf ** Fa ap .
 If
-.Pf * Fa a
+.Pf * Fa ap
 is
 .Dv NULL ,
 a new
 .Vt BIGNUM
 is created.
 If
-.Fa a
+.Fa ap
 is
 .Dv NULL ,
 it only computes the number's length in hexadecimal digits,
@@ -230,7 +277,7 @@ stores the representation of
 at
 .Fa to ,
 where
-.Fa to
+.Pf * Fa to
 must be large enough to hold the result.
 The size can be determined by calling
 .Fn BN_bn2mpi a  NULL .
@@ -254,8 +301,17 @@ is
 .Fn BN_bn2bin
 returns the length of the big-endian number placed at
 .Fa to .
+.Pp
+.Fn BN_bn2binpad
+and
+.Fn BN_bn2lebinpad
+return the number of bytes written
+or \-1 if the supplied buffer is too small.
+.Pp
 .Fn BN_bin2bn
-returns the
+and
+.Fn BN_lebin2bn
+return the
 .Vt BIGNUM ,
 or
 .Dv NULL
@@ -297,6 +353,7 @@ on error.
 The error codes can be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_INTEGER_to_BN 3 ,
 .Xr BN_new 3 ,
 .Xr BN_num_bytes 3 ,
 .Xr BN_zero 3
@@ -322,3 +379,10 @@ All these functions have been available since
 .Fn BN_asc2bin
 first appeared in OpenSSL 1.0.0 and has been available since
 .Ox 4.9 .
+.Pp
+.Fn BN_bn2binpad ,
+.Fn BN_bn2lebinpad ,
+and
+.Fn BN_lebin2bn
+first appeared in OpenSSL 1.1.0 and have been available since
+.Ox 7.0 .