document X509_signature_dump(3) and X509_signature_print(3)

5 files changed, 97 insertions, 9 deletions

diff --git a/lib/libcrypto/man/ASN1_STRING_print_ex.3 b/lib/libcrypto/man/ASN1_STRING_print_ex.3
index df09247216c..43673bc0f7b 100644
--- a/lib/libcrypto/man/ASN1_STRING_print_ex.3
+++ b/lib/libcrypto/man/ASN1_STRING_print_ex.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.15 2019/06/06 01:06:58 schwarze Exp $
+.\" $OpenBSD: ASN1_STRING_print_ex.3,v 1.16 2021/07/06 16:05:44 schwarze Exp $
 .\" full merge up to: OpenSSL bb9ad09e Jun 6 00:43:05 2016 -0400
 .\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
@@ -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 6 2019 $
+.Dd $Mdocdate: July 6 2021 $
 .Dt ASN1_STRING_PRINT_EX 3
 .Os
 .Sh NAME
@@ -221,7 +221,8 @@ returns 1 on success or 0 on error.
 returns a static string.
 .Sh SEE ALSO
 .Xr ASN1_STRING_new 3 ,
-.Xr X509_NAME_print_ex 3
+.Xr X509_NAME_print_ex 3 ,
+.Xr X509_signature_dump 3
 .Sh HISTORY
 .Fn ASN1_STRING_print
 first appeared in SSLeay 0.6.5 and has been available since
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 2087fbae707..974fd918f3a 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.172 2021/07/04 12:56:27 schwarze Exp $
+# $OpenBSD: Makefile,v 1.173 2021/07/06 16:05:44 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -317,6 +317,7 @@ MAN=	\
 	X509_get1_email.3 \
 	X509_new.3 \
 	X509_sign.3 \
+	X509_signature_dump.3 \
 	X509_verify_cert.3 \
 	X509v3_get_ext_by_NID.3 \
 	crypto.3 \
diff --git a/lib/libcrypto/man/X509_ALGOR_dup.3 b/lib/libcrypto/man/X509_ALGOR_dup.3
index 99c65b00f38..2cfe36184dd 100644
--- a/lib/libcrypto/man/X509_ALGOR_dup.3
+++ b/lib/libcrypto/man/X509_ALGOR_dup.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: X509_ALGOR_dup.3,v 1.15 2021/03/12 05:18:00 jsg Exp $
+.\"	$OpenBSD: X509_ALGOR_dup.3,v 1.16 2021/07/06 16:05:44 schwarze Exp $
 .\"	OpenSSL 4692340e Jun 7 15:49:08 2016 -0400
 .\"
 .\" This file is a derived work.
@@ -65,7 +65,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 6 2021 $
 .Dt X509_ALGOR_DUP 3
 .Os
 .Sh NAME
@@ -210,7 +210,8 @@ have identical encodings or non-zero otherwise.
 .Xr EVP_DigestInit 3 ,
 .Xr X509_get0_signature 3 ,
 .Xr X509_new 3 ,
-.Xr X509_PUBKEY_get0_param 3
+.Xr X509_PUBKEY_get0_param 3 ,
+.Xr X509_signature_dump 3
 .Sh STANDARDS
 RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
 Certificate Revocation List (CRL) Profile
diff --git a/lib/libcrypto/man/X509_get0_signature.3 b/lib/libcrypto/man/X509_get0_signature.3
index 903cc043d9a..7082db160c0 100644
--- a/lib/libcrypto/man/X509_get0_signature.3
+++ b/lib/libcrypto/man/X509_get0_signature.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_get0_signature.3,v 1.6 2020/06/24 19:55:55 schwarze Exp $
+.\" $OpenBSD: X509_get0_signature.3,v 1.7 2021/07/06 16:05:44 schwarze Exp $
 .\" selective merge up to:
 .\" OpenSSL man3/X509_get0_signature 2f7a2520 Apr 25 17:28:08 2017 +0100
 .\"
@@ -66,7 +66,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: June 24 2020 $
+.Dd $Mdocdate: July 6 2021 $
 .Dt X509_GET0_SIGNATURE 3
 .Os
 .Sh NAME
@@ -177,6 +177,7 @@ is not appropriate, for example in a non-standard or unsupported format.
 .Xr X509_new 3 ,
 .Xr X509_REQ_new 3 ,
 .Xr X509_sign 3 ,
+.Xr X509_signature_dump 3 ,
 .Xr X509_verify_cert 3
 .Sh HISTORY
 .Fn X509_get_signature_type
diff --git a/lib/libcrypto/man/X509_signature_dump.3 b/lib/libcrypto/man/X509_signature_dump.3
new file mode 100644
index 00000000000..8fff79ce898
--- /dev/null
+++ b/lib/libcrypto/man/X509_signature_dump.3
@@ -0,0 +1,84 @@
+.\" $OpenBSD: X509_signature_dump.3,v 1.1 2021/07/06 16:05:44 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 6 2021 $
+.Dt X509_SIGNATURE_DUMP 3
+.Os
+.Sh NAME
+.Nm X509_signature_dump ,
+.Nm X509_signature_print
+.Nd pretty-print ASN.1 strings
+.Sh SYNOPSIS
+.In openssl/x509.h
+.Ft int
+.Fo X509_signature_dump
+.Fa "BIO *bio"
+.Fa "const ASN1_STRING *signature"
+.Fa "int indent"
+.Fc
+.Ft int
+.Fo X509_signature_print
+.Fa "BIO *bio"
+.Fa "const X509_ALGOR *algorithm"
+.Fa "const ASN1_STRING *signature"
+.Fc
+.Sh DESCRIPTION
+.Fn X509_signature_dump
+writes the data bytes contained in the
+.Fa signature
+to
+.Fa bio
+in hexadecimal format with colons between bytes,
+18 bytes per output line, each line indented with
+.Fa indent
+space characters.
+.Pp
+.Fn X509_signature_print
+writes the name of the signature
+.Fa algorithm ,
+or, if no name for it is known, its object identifier (OID) to
+.Fa bio
+using
+.Xr i2a_ASN1_OBJECT 3 .
+After that, if a method object for the algorithm can be retrieved with
+.Xr EVP_PKEY_asn1_find 3
+and if that object defines a printing method, that printing method is
+used to print the
+.Fa signature .
+Otherwise, unless the
+.Fa signature
+is
+.Dv NULL ,
+it is printed using
+.Fn X509_signature_dump .
+.Sh RETURN VALUES
+These functions return 1 on success or 0 on failure.
+They fail and return as soon as any write operation fails.
+.Sh SEE ALSO
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_STRING_print_ex 3 ,
+.Xr BIO_new 3 ,
+.Xr EVP_PKEY_asn1_new 3 ,
+.Xr X509_ALGOR_new 3 ,
+.Xr X509_get0_signature 3
+.Sh HISTORY
+.Fn X509_signature_print
+first appeared in OpenSSL 0.9.7 and has been available since
+.Ox 3.2 .
+.Pp
+.Fn X509_signature_dump
+first appeared in OpenSSL 1.0.1 and has been available since
+.Ox 5.3 .