document ASN1_item_pack(3) and ASN1_item_unpack(3)

5 files changed, 94 insertions, 6 deletions

diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index 54c5f7163fd..a2cd27ecb85 100644
--- a/lib/libcrypto/man/ASN1_STRING_new.3
+++ b/lib/libcrypto/man/ASN1_STRING_new.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: ASN1_STRING_new.3,v 1.19 2021/11/15 10:41:11 schwarze Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.20 2021/11/15 11:51:09 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -204,6 +204,7 @@ is returned and an error code can be retrieved with
 .Xr ERR_get_error 3 .
 .Sh SEE ALSO
 .Xr ASN1_INTEGER_get 3 ,
+.Xr ASN1_item_pack 3 ,
 .Xr ASN1_mbstring_copy 3 ,
 .Xr ASN1_STRING_length 3 ,
 .Xr ASN1_STRING_print_ex 3 ,
diff --git a/lib/libcrypto/man/ASN1_item_d2i.3 b/lib/libcrypto/man/ASN1_item_d2i.3
index 19b290ef637..8f716f6f365 100644
--- a/lib/libcrypto/man/ASN1_item_d2i.3
+++ b/lib/libcrypto/man/ASN1_item_d2i.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_item_d2i.3,v 1.11 2021/11/07 15:29:01 schwarze Exp $
+.\"     $OpenBSD: ASN1_item_d2i.3,v 1.12 2021/11/15 11:51:09 schwarze Exp $
 .\"     OpenSSL doc/man3/d2i_X509.pod b97fdb57 Nov 11 09:33:09 2016 +0100
 .\"
 .\" 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: November 7 2021 $
+.Dd $Mdocdate: November 15 2021 $
 .Dt ASN1_ITEM_D2I 3
 .Os
 .Sh NAME
@@ -364,6 +364,7 @@ if (d2i_X509(&x, &p, len) == NULL)
 .Xr ASN1_get_object 3 ,
 .Xr ASN1_item_digest 3 ,
 .Xr ASN1_item_new 3 ,
+.Xr ASN1_item_pack 3 ,
 .Xr ASN1_item_sign 3 ,
 .Xr ASN1_item_verify 3 ,
 .Xr ASN1_TYPE_new 3
diff --git a/lib/libcrypto/man/ASN1_item_new.3 b/lib/libcrypto/man/ASN1_item_new.3
index fd967bfc3fb..12340c7443e 100644
--- a/lib/libcrypto/man/ASN1_item_new.3
+++ b/lib/libcrypto/man/ASN1_item_new.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ASN1_item_new.3,v 1.7 2021/11/07 15:29:01 schwarze Exp $
+.\" $OpenBSD: ASN1_item_new.3,v 1.8 2021/11/15 11:51:09 schwarze Exp $
 .\"
 .\" Copyright (c) 2016, 2018 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: November 7 2021 $
+.Dd $Mdocdate: November 15 2021 $
 .Dt ASN1_ITEM_NEW 3
 .Os
 .Sh NAME
@@ -108,6 +108,7 @@ is returned and an error code can be retrieved with
 .Xr ASN1_get_object 3 ,
 .Xr ASN1_item_d2i 3 ,
 .Xr ASN1_item_digest 3 ,
+.Xr ASN1_item_pack 3 ,
 .Xr ASN1_item_sign 3 ,
 .Xr ASN1_item_verify 3 ,
 .Xr ASN1_TYPE_new 3 ,
diff --git a/lib/libcrypto/man/ASN1_item_pack.3 b/lib/libcrypto/man/ASN1_item_pack.3
new file mode 100644
index 00000000000..4c87530622f
--- /dev/null
+++ b/lib/libcrypto/man/ASN1_item_pack.3
@@ -0,0 +1,84 @@
+.\" $OpenBSD: ASN1_item_pack.3,v 1.1 2021/11/15 11:51:09 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: November 15 2021 $
+.Dt ASN1_ITEM_PACK 3
+.Os
+.Sh NAME
+.Nm ASN1_item_pack ,
+.Nm ASN1_item_unpack
+.Nd pack an ASN.1 object into an ASN1_STRING
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft ASN1_STRING *
+.Fo ASN1_item_pack
+.Fa "void *val_in"
+.Fa "const ASN1_ITEM *it"
+.Fa "ASN1_STRING **string_out"
+.Fc
+.Ft void *
+.Fo ASN1_item_unpack
+.Fa "const ASN1_STRING *string_in"
+.Fa "const ASN1_ITEM *it"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_item_pack
+encodes the object pointed to by
+.Fa val_in
+into DER format using
+.Xr ASN1_item_i2d 3
+and stores the encoded form in
+.Pf ** Fa string_out .
+If
+.Fa string_out
+or
+.Pf * Fa string_out
+is a
+.Dv NULL
+pointer, a new
+.Vt ASN1_STRING
+object is allocated and returned.
+.Pp
+.Fn ASN1_item_unpack
+interprets the data in
+.Fa string_in
+as a DER- or BER-encoded byte array and decodes one value of the type
+.Fa it
+into a newly allocated object using
+.Xr ASN1_item_d2i 3 .
+.Sh RETURN VALUES
+.Fn ASN1_item_pack
+returns the modified or new object or
+.Dv NULL
+if memory allocation or encoding fails.
+.Pp
+.Fn ASN1_item_unpack
+returns the new object or
+.Dv NULL
+if memory allocation or decoding fails.
+.Sh SEE ALSO
+.Xr ASN1_item_d2i 3 ,
+.Xr ASN1_item_new 3 ,
+.Xr ASN1_STRING_new 3
+.Sh HISTORY
+.Fn ASN1_item_pack
+and
+.Fn ASN1_item_unpack
+first appeared in OpenSSL 0.9.7 and have been available since
+.Ox 3.2 .
+.Sh BUGS
+See the BUGS section in
+.Xr ASN1_item_i2d 3 .
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index a1e1c97b81d..ab7740054ea 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.212 2021/11/15 10:41:11 schwarze Exp $
+# $OpenBSD: Makefile,v 1.213 2021/11/15 11:51:09 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -18,6 +18,7 @@ MAN=	\
 	ASN1_item_d2i.3 \
 	ASN1_item_digest.3 \
 	ASN1_item_new.3 \
+	ASN1_item_pack.3 \
 	ASN1_item_sign.3 \
 	ASN1_item_verify.3 \
 	ASN1_mbstring_copy.3 \