new manual page BIO_dump(3)

3 files changed, 149 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/BIO_dump.3 b/src/lib/libcrypto/man/BIO_dump.3
new file mode 100644
index 0000000000..88ae7d571d
--- /dev/null
+++ b/src/lib/libcrypto/man/BIO_dump.3
@@ -0,0 +1,144 @@
+.\" $OpenBSD: BIO_dump.3,v 1.1 2021/07/10 15:56:18 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: July 10 2021 $
+.Dt BIO_DUMP 3
+.Os
+.Sh NAME
+.Nm BIO_dump ,
+.Nm BIO_dump_indent ,
+.Nm BIO_dump_fp ,
+.Nm BIO_dump_indent_fp
+.Nd hexadecimal printout of arbitrary byte arrays
+.Sh SYNOPSIS
+.In openssl/bio.h
+.Ft int
+.Fo BIO_dump
+.Fa "BIO *b"
+.Fa "const char *s"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo BIO_dump_indent
+.Fa "BIO *b"
+.Fa "const char *s"
+.Fa "int len"
+.Fa "int indent"
+.Fc
+.Ft int
+.Fo BIO_dump_fp
+.Fa "FILE *fp"
+.Fa "const char *s"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo BIO_dump_indent_fp
+.Fa "FILE *fp"
+.Fa "const char *s"
+.Fa "int len"
+.Fa "int indent"
+.Fc
+.Sh DESCRIPTION
+.Fn BIO_dump
+prints
+.Fa len
+bytes starting at
+.Fa s
+to
+.Fa bio
+in hexadecimal format.
+.Pp
+The first column of output contains the index, in the byte array starting at
+.Fa s ,
+of the first byte shown on the respective output line, expressed as a
+four-digit hexadecimal number starting at 0000, followed by a dash.
+After the dash, sixteen bytes of data are printed as two-digit
+hexadecimal numbers, respecting the order in which they appear in
+the array
+.Fa s .
+Another dash is printed after the eighth column.
+.Pp
+To the right of the hexadecimal representation of the bytes,
+the same bytes are printed again, this time as ASCII characters.
+Non-printable ASCII characters are replaced with dots.
+.Pp
+Trailing space characters and NUL bytes are omitted from the main table.
+If there are any, an additional line is printed, constisting of the
+.Fa len
+argument as a four-digit hexadecimal number, a dash, and the fixed string
+.Qq <SPACES/NULS> .
+.Pp
+.Fn BIO_dump_indent
+is similar except that
+.Fa indent
+space characters are prepended to each output line.
+If
+.Fa indent
+is 7 or more, the number of data columns is reduced such that the
+total width of the output does not exceed 79 characters per line.
+.Pp
+.Fn BIO_dump_fp
+and
+.Fn BIO_dump_indent_fp
+are similar except that
+.Xr fwrite 3
+is used instead of
+.Xr BIO_write 3 .
+.Sh RETURN VALUES
+These functions return the sum of the return values of all calls to
+.Xr BIO_write 3
+or
+.Xr fwrite 3
+that were made.
+This is useless because it may add a positive number, the total amount
+of bytes written by successful calls to
+.Xr BIO_write 3 ,
+to an incommensurable negative number, usually the number of calls to
+.Xr BIO_write 3
+that failed.
+All that can be said is that a negative return value indicates that
+at least part of the printing failed, and a positive return value
+indicates that at least some of the printing succeeded, but one
+cannot tell whether success or failure were partial or complete.
+Furthermore, a zero return value does not necessarily mean that
+nothing was printed; it can also occur if a part of the printing
+succeeded and another part failed.
+.Sh SEE ALSO
+.Xr hexdump 1 ,
+.Xr BIO_new 3 ,
+.Xr BIO_write 3
+.Sh HISTORY
+.Fn BIO_dump
+first appeared in SSLeay 0.6.5 and has been available since
+.Ox 2.4 .
+.Pp
+.Fn BIO_dump_indent
+first appeared in OpenSSL 0.9.6 and has been available since
+.Ox 2.9 .
+.Pp
+.Fn BIO_dump_fp
+and
+.Fn BIO_dump_indent_fp
+first appeared in OpenSSL 0.9.8 and have been available since
+.Ox 4.5 .
+.Sh BUGS
+If some parts of the printing operations succeed
+and some other parts fail,
+.Fn BIO_dump
+may silently yield incomplete results
+such that the caller cannot detect the partial failure.
+Besides, the function may have written more bytes than the return
+value indicates.
diff --git a/src/lib/libcrypto/man/BIO_new.3 b/src/lib/libcrypto/man/BIO_new.3
index a2bc40d368..e7c08c99f1 100644
--- a/src/lib/libcrypto/man/BIO_new.3
+++ b/src/lib/libcrypto/man/BIO_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: BIO_new.3,v 1.20 2021/03/12 07:05:35 jmc Exp $
+.\" $OpenBSD: BIO_new.3,v 1.21 2021/07/10 15:56:18 schwarze Exp $
 .\" full merge up to:
 .\" OpenSSL man3/BIO_new.pod fb46be03 Feb 26 11:51:31 2016 +0000
 .\" OpenSSL man7/bio.pod 631c37be Dec 12 16:56:50 2017 +0100
@@ -52,7 +52,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: March 12 2021 $
+.Dd $Mdocdate: July 10 2021 $
 .Dt BIO_NEW 3
 .Os
 .Sh NAME
@@ -229,6 +229,7 @@ Create a memory BIO:
 .Dl BIO *mem = BIO_new(BIO_s_mem());
 .Sh SEE ALSO
 .Xr BIO_ctrl 3 ,
+.Xr BIO_dump 3 ,
 .Xr BIO_f_base64 3 ,
 .Xr BIO_f_buffer 3 ,
 .Xr BIO_f_cipher 3 ,
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index bf76a1ce74..46a7d3beb2 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.175 2021/07/09 12:07:27 schwarze Exp $
+# $OpenBSD: Makefile,v 1.176 2021/07/10 15:56:18 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -22,6 +22,7 @@ MAN=	\
         BASIC_CONSTRAINTS_new.3 \
         BF_set_key.3 \
         BIO_ctrl.3 \
+        BIO_dump.3 \
         BIO_f_base64.3 \
         BIO_f_buffer.3 \
         BIO_f_cipher.3 \