document i2a_ASN1_STRING(3) and a2i_ASN1_STRING(3)

3 files changed, 163 insertions, 3 deletions

diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index ce2e9fdc68c..54c5f7163fd 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.18 2021/10/20 13:14:00 schwarze Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.19 2021/11/15 10:41:11 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -15,7 +15,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: October 20 2021 $
+.Dd $Mdocdate: November 15 2021 $
 .Dt ASN1_STRING_NEW 3
 .Os
 .Sh NAME
@@ -212,6 +212,7 @@ is returned and an error code can be retrieved with
 .Xr ASN1_TYPE_get 3 ,
 .Xr d2i_ASN1_OBJECT 3 ,
 .Xr d2i_ASN1_OCTET_STRING 3 ,
+.Xr i2a_ASN1_STRING 3 ,
 .Xr X509_cmp_time 3 ,
 .Xr X509_EXTENSION_get_object 3 ,
 .Xr X509_get_ext_by_OBJ 3 ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 4a22484ea30..a1e1c97b81d 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.211 2021/11/11 12:06:25 schwarze Exp $
+# $OpenBSD: Makefile,v 1.212 2021/11/15 10:41:11 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -398,6 +398,7 @@ MAN=	\
 	des_read_pw.3 \
 	evp.3 \
 	get_rfc3526_prime_8192.3 \
+	i2a_ASN1_STRING.3 \
 	i2d_CMS_bio_stream.3 \
 	i2d_PKCS7_bio_stream.3 \
 	lh_new.3 \
diff --git a/lib/libcrypto/man/i2a_ASN1_STRING.3 b/lib/libcrypto/man/i2a_ASN1_STRING.3
new file mode 100644
index 00000000000..fa5f071c14d
--- /dev/null
+++ b/lib/libcrypto/man/i2a_ASN1_STRING.3
@@ -0,0 +1,158 @@
+.\" $OpenBSD: i2a_ASN1_STRING.3,v 1.1 2021/11/15 10:41:11 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 I2A_ASN1_STRING 3
+.Os
+.Sh NAME
+.Nm i2a_ASN1_STRING ,
+.Nm a2i_ASN1_STRING
+.Nd hexadecimal dump of an ASN.1 string
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft int
+.Fo i2a_ASN1_STRING
+.Fa "BIO *out_bio"
+.Fa "const ASN1_STRING *a"
+.Fa "int type"
+.Fc
+.Ft int
+.Fo a2i_ASN1_STRING
+.Fa "BIO *in_bio"
+.Fa "ASN1_STRING *out_string"
+.Fa "char *buffer"
+.Fa "int size"
+.Fc
+.Sh DESCRIPTION
+The function
+.Fn i2a_ASN1_STRING
+writes a hexadecimal representation of
+.Fa a
+to
+.Fa out_bio .
+The
+.Fa type
+argument is ignored.
+.Pp
+Each byte of
+.Xr ASN1_STRING_get0_data 3
+is written as a number consisting of two upper-case hexadecimal digits.
+After each group of 70 digits, a backslash and a linefeed
+are inserted before the next digit.
+.Pp
+If the
+.Xr ASN1_STRING_length 3
+of
+.Fa a
+is 0, the single digit
+.Ql 0
+is written instead.
+If
+.Fa a
+is a
+.Dv NULL
+pointer, nothing is written.
+.Pp
+The function
+.Fn a2i_ASN1_STRING
+parses a hexadecimal representation of an ASN.1 string into
+.Fa out_string .
+Both lower-case and upper-case hexadecimal digits are accepted.
+Every pair of input digits is converted into one output byte.
+At least one pair of input digits is required.
+.Pp
+On every input line, the trailing newline character and an optional
+carrier return character character preceding it are ignored.
+The trailing newline need not be present on the last line.
+If there is a backslash character before the newline character,
+parsing is continued on the next input line.
+In particular,
+.Fn a2i_ASN1_STRING
+is able to parse the output of
+.Fn i2a_ASN1_STRING
+except when the
+.Xr ASN1_STRING_length 3
+of
+.Fa a
+was 0.
+.Pp
+Parsing fails if an input line contains an odd number of input
+digits or if memory allocation fails.
+.Pp
+This function uses the
+.Fa buffer
+provided by the caller and assumes it is at least
+.Fa size
+bytes long.
+It is unspecified what the buffer contains after the function returns.
+.Sh RETURN VALUES
+The function
+.Fn i2a_ASN1_STRING
+returns the number of bytes written or \-1 if
+.Xr BIO_write 3
+fails.
+.Pp
+The function
+.Fn a2i_ASN1_STRING
+is intended to return 1 for success or 0 for failure, but see the
+.Sx BUGS
+section for a number of traps.
+.Sh SEE ALSO
+.Xr ASN1_STRING_length 3 ,
+.Xr ASN1_STRING_new 3 ,
+.Xr ASN1_STRING_print_ex 3 ,
+.Xr i2a_ASN1_INTEGER 3 ,
+.Xr i2a_ASN1_OBJECT 3
+.Sh HISTORY
+These functions first appeared in SSLeay 0.6.5.
+The function
+.Fn a2i_ASN1_STRING
+has been part of the public API since SSLeay 0.6.5 and
+.Fn i2a_ASN1_STRING
+since SSLeay 0.8.0.
+They have been available since
+.Ox 2.4 .
+.Sh BUGS
+If the first call to
+.Xr BIO_gets 3
+does not return any data, even if that is caused by a fatal I/O error,
+if the BIO type does not support the
+.Dq gets
+operation, or if it is caused by the BIO being non-blocking,
+.Fn a2i_ASN1_STRING
+immediately succeeds and returns an empty
+.Fa out_string .
+.Pp
+If
+.Fn BIO_gets 3
+returns a partial line, for example because the given
+.Fa size
+is insufficient to contain one of the input lines
+or for reasons specific to the BIO type,
+.Fn a2i_ASN1_STRING
+may fail or silently return a truncated result.
+The caller is responsible for providing a
+.Fa buffer
+of sufficient size to contain the longest possible input line
+and for choosing a BIO of a type that only returns complete
+input lines and does not perform partial reads.
+.Pp
+The function
+.Fn a2i_ASN1_STRING
+does not support non-blocking BIOs.
+Reading is terminated as soon as
+.Xr BIO_gets 3
+returns a value less than 1.