From 6370c4e2f1674f11719acba9695f53df09bd66f5 Mon Sep 17 00:00:00 2001
From: schwarze <schwarze@openbsd.org>
Date: Tue, 23 Nov 2021 14:58:08 +0000
Subject: [PATCH] document ASN1_TYPE_set_octetstring(3) and
 ASN1_TYPE_get_octetstring(3)

---
 lib/libcrypto/man/ASN1_TYPE_get.3 | 72 ++++++++++++++++++++++++++++---
 1 file changed, 67 insertions(+), 5 deletions(-)

diff --git a/lib/libcrypto/man/ASN1_TYPE_get.3 b/lib/libcrypto/man/ASN1_TYPE_get.3
index 6a7d761f942..d4123cb3a9f 100644
--- a/lib/libcrypto/man/ASN1_TYPE_get.3
+++ b/lib/libcrypto/man/ASN1_TYPE_get.3
@@ -1,10 +1,10 @@
-.\"	$OpenBSD: ASN1_TYPE_get.3,v 1.13 2021/11/21 15:11:01 schwarze Exp $
+.\"	$OpenBSD: ASN1_TYPE_get.3,v 1.14 2021/11/23 14:58:08 schwarze Exp $
 .\"	OpenSSL 99d63d46 Mon Jun 6 00:43:05 2016 -0400
 .\"
 .\" This file is a derived work.
 .\" The changes are covered by the following Copyright and license:
 .\"
-.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
+.\" Copyright (c) 2017, 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
@@ -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 21 2021 $
+.Dd $Mdocdate: November 23 2021 $
 .Dt ASN1_TYPE_GET 3
 .Os
 .Sh NAME
@@ -74,6 +74,8 @@
 .Nm ASN1_TYPE_get ,
 .Nm ASN1_TYPE_set ,
 .Nm ASN1_TYPE_set1 ,
+.Nm ASN1_TYPE_set_octetstring ,
+.Nm ASN1_TYPE_get_octetstring ,
 .Nm ASN1_TYPE_cmp
 .Nd ASN.1 objects of arbitrary type
 .Sh SYNOPSIS
@@ -99,6 +101,18 @@
 .Fa "const void *value"
 .Fc
 .Ft int
+.Fo ASN1_TYPE_set_octetstring
+.Fa "ASN1_TYPE *a"
+.Fa "const unsigned char *data"
+.Fa "int len"
+.Fc
+.Ft int
+.Fo ASN1_TYPE_get_octetstring
+.Fa "const ASN1_TYPE *a"
+.Fa "unsigned char *buffer"
+.Fa "int buflen"
+.Fc
+.Ft int
 .Fo ASN1_TYPE_cmp
 .Fa "const ASN1_TYPE *a"
 .Fa "const ASN1_TYPE *b"
@@ -216,6 +230,33 @@ then the
 contains the entire ASN.1 encoding verbatim, including tag and
 length octets.
 .Pp
+.Fn ASN1_TYPE_set_octetstring
+allocates a new
+.Vt ASN1_OCTET_STRING
+object, copies
+.Fa len
+bytes of
+.Fa data
+into it using
+.Xr ASN1_STRING_set 3 ,
+and replaces the value of
+.Fa a
+with it by calling
+.Fn ASN1_TYPE_set
+with a type of
+.Dv V_ASN1_OCTET_STRING .
+.Pp
+.Fn ASN1_TYPE_get_octetstring
+copies the contents of the
+.Vt ASN1_OCTET_STRING
+object contained in
+.Fa a ,
+but not more than
+.Fa buflen
+bytes, into the
+.Fa buffer
+provided by the caller.
+.Pp
 .Fn ASN1_TYPE_cmp
 checks that
 .Fa a
@@ -269,7 +310,24 @@ newly constructed with
 .Fn ASN1_TYPE_new .
 .Pp
 .Fn ASN1_TYPE_set1
-returns 1 if the copying succeeds or 0 if it fails.
+and
+.Fn ASN1_TYPE_set_octetstring
+return 1 if the copying succeeds or 0 if it fails.
+.Pp
+.Fn ASN1_TYPE_get_octetstring
+returns the number of data bytes contained in the
+.Vt ASN1_OCTET_STRING
+object contained in
+.Fa a
+or \-1 if
+.Fa a
+is not of the type
+.Dv V_ASN1_OCTET_STRING
+or does not contain any object.
+If the return value is greater than the
+.Fa buflen
+argument, the content was truncated when copied to the
+.Fa buffer .
 .Pp
 .Fn ASN1_TYPE_cmp
 returns 0 for a match or non-zero for a mismatch.
@@ -296,7 +354,11 @@ first appeared in SSLeay 0.5.1.
 .Fn ASN1_TYPE_get
 and
 .Fn ASN1_TYPE_set
-first appeared in SSLeay 0.8.0.
+in SSLeay 0.8.0, and
+.Fn ASN1_TYPE_set_octetstring
+and
+.Fn ASN1_TYPE_get_octetstring
+in SSLeay 0.9.0.
 These functions have been available since
 .Ox 2.4 .
 .Pp
-- 
2.20.1