new manual page ASN1_bn_print(3)

4 files changed, 126 insertions, 5 deletions

diff --git a/lib/libcrypto/man/ASN1_bn_print.3 b/lib/libcrypto/man/ASN1_bn_print.3
new file mode 100644
index 00000000000..75944917de1
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_bn_print.3
@@ -0,0 +1,118 @@
+.\" $OpenBSD: ASN1_bn_print.3,v 1.1 2021/12/08 21:52:29 schwarze Exp $
+.\"
+.\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" Permission to use, copy, modify, and distribute this software for any
+.\" purpose with or without fee is hereby granted, provided that the above
+.\" copyright notice and this permission notice appear in all copies.
+.\"
+.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+.\"
+.Dd $Mdocdate: December 8 2021 $
+.Dt ASN1_BN_PRINT 3
+.Os
+.Sh NAME
+.Nm ASN1_bn_print
+.Nd pretty-print a BIGNUM object
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo ASN1_bn_print
+.Fa "BIO *bio_out"
+.Fa "const char *label"
+.Fa "const BIGNUM *bn"
+.Fa "unsigned char *buffer"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_bn_print
+prints
+.Fa bn
+to
+.Fa bio_out
+in human-readable form.
+Despite its name and the header file,
+this function has nothing to do with ASN.1.
+.Pp
+The caller is responsible for providing a
+.Fa buffer
+that is at least
+.Fn BN_num_bytes bn
++ 1 bytes long.
+To avoid a buffer overrun, be careful to not forget the
+.Dq plus one .
+It is unspecified what the buffer may contain after the function returns.
+.Pp
+If
+.Fa indent
+is greater than zero,
+.Fa indent
+space characters are printed first, but not more than 128.
+.Pp
+The NUL-terminated
+.Fa label
+is printed next.
+.Pp
+After that, there are three cases:
+.Bl -bullet
+.It
+If
+.Fa bn
+represents the number zero,
+.Qq 0
+is printed.
+.It
+If
+.Fa bn
+can be represented by the data type
+.Vt unsigned long ,
+it is printed in decimal notation,
+followed by hexadecimal notation in parentheses,
+both optionally preceded by a minus sign.
+.It
+Otherwise, the string
+.Qq Pq Negative
+is printed if appropriate, a new output line is started,
+and the indentation is increased by four space characters.
+The bytes of the value of
+.Fa bn
+are then printed in big-endian order, each byte represented
+by a two-digit hexadecimal number,
+and each but the last byte followed by a colon.
+A new output line is started after every group of 15 bytes.
+.El
+.Pp
+Finally, a newline character is printed to end the output.
+.Pp
+If
+.Fa bn
+is a
+.Dv NULL
+pointer, all arguments are ignored and nothing is printed.
+.Sh RETURN VALUES
+.Fn ASN1_bn_print
+returns 1
+if successful or if
+.Fa bn
+is a
+.Dv NULL
+pointer.
+It returns 0 if printing fails.
+.Sh SEE ALSO
+.Xr BIO_new 3 ,
+.Xr BIO_write 3 ,
+.Xr BN_is_negative 3 ,
+.Xr BN_is_zero 3 ,
+.Xr BN_new 3 ,
+.Xr BN_num_bytes 3 ,
+.Xr BN_print 3
+.Sh HISTORY
+.Fn ASN1_bn_print
+first appeared in OpenSSL 1.0.0 and has been available since
+.Ox 4.9 .
diff --git a/lib/libcrypto/man/BN_bn2bin.3 b/lib/libcrypto/man/BN_bn2bin.3
index 48d350ab483..ec69909d9df 100644
--- a/lib/libcrypto/man/BN_bn2bin.3
+++ b/lib/libcrypto/man/BN_bn2bin.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BN_bn2bin.3,v 1.14 2021/09/11 08:45:47 schwarze Exp $
+.\" $OpenBSD: BN_bn2bin.3,v 1.15 2021/12/08 21:52:29 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>
@@ -49,7 +49,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: September 11 2021 $
+.Dd $Mdocdate: December 8 2021 $
 .Dt BN_BN2BIN 3
 .Os
 .Sh NAME
@@ -353,6 +353,7 @@ on error.
 The error codes can be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_bn_print 3 ,
 .Xr ASN1_INTEGER_to_BN 3 ,
 .Xr BN_new 3 ,
 .Xr BN_num_bytes 3 ,
diff --git a/lib/libcrypto/man/BN_new.3 b/lib/libcrypto/man/BN_new.3
index bb637a974f6..ada4acf1754 100644
--- a/lib/libcrypto/man/BN_new.3
+++ b/lib/libcrypto/man/BN_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BN_new.3,v 1.16 2019/06/10 09:49:48 schwarze Exp $
+.\" $OpenBSD: BN_new.3,v 1.17 2021/12/08 21:52:29 schwarze Exp $
 .\" full merge up to: OpenSSL man3/BN_new 2457c19d Mar 6 08:43:36 2004 +0000
 .\" selective merge up to: man3/BN_new 681acb31 Sep 29 13:10:34 2017 +0200
 .\" full merge up to: OpenSSL man7/bn 05ea606a May 20 20:52:46 2016 -0400
@@ -50,7 +50,7 @@
 .\" 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: December 8 2021 $
 .Dt BN_NEW 3
 .Os
 .Sh NAME
@@ -144,6 +144,7 @@ If the allocation fails, it returns
 and sets an error code that can be obtained by
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
+.Xr ASN1_bn_print 3 ,
 .Xr BN_add 3 ,
 .Xr BN_add_word 3 ,
 .Xr BN_BLINDING_new 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 6d5f8d982b5..91c763c8ed5 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.221 2021/11/27 16:18:03 schwarze Exp $
+# $OpenBSD: Makefile,v 1.222 2021/12/08 21:52:29 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -18,6 +18,7 @@ MAN=	\
 	ASN1_TIME_set.3 \
 	ASN1_TYPE_get.3 \
 	ASN1_UNIVERSALSTRING_to_string.3 \
+	ASN1_bn_print.3 \
 	ASN1_generate_nconf.3 \
 	ASN1_get_object.3 \
 	ASN1_item_d2i.3 \