From 26ded6b71c98a0c1f740fa6c91f43c9704dc7347 Mon Sep 17 00:00:00 2001 From: Ingo Schwarze Date: Wed, 8 Dec 2021 21:52:30 +0000 Subject: new manual page ASN1_bn_print(3) --- lib/libcrypto/man/ASN1_bn_print.3 | 118 ++++++++++++++++++++++++++++++++++++++ lib/libcrypto/man/BN_bn2bin.3 | 5 +- lib/libcrypto/man/BN_new.3 | 5 +- lib/libcrypto/man/Makefile | 3 +- 4 files changed, 126 insertions(+), 5 deletions(-) create mode 100644 lib/libcrypto/man/ASN1_bn_print.3 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 +.\" +.\" 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 @@ -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 @@ -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 \ -- cgit v1.2.3