Write new d2i_ASN1_OCTET_STRING(3) manual page from scratch.

All 36 functions listed in <openssl/asn1.h>
and in OpenSSL doc/man3/d2i_X509.pod,
six of them with wrong prototypes.

3 files changed, 373 insertions, 2 deletions

diff --git a/lib/libcrypto/man/ASN1_STRING_new.3 b/lib/libcrypto/man/ASN1_STRING_new.3
index 65be8c471bd..df5f499423b 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.8 2017/01/05 08:24:38 jmc Exp $
+.\"	$OpenBSD: ASN1_STRING_new.3,v 1.9 2017/01/05 22:38:04 schwarze Exp $
 .\"	OpenSSL 99d63d46 Tue Mar 24 07:52:24 2015 -0400
 .\"
 .\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
@@ -204,6 +204,7 @@ if an error occurs.
 .Sh SEE ALSO
 .Xr ASN1_time_parse 3 ,
 .Xr ASN1_TIME_set 3 ,
+.Xr d2i_ASN1_OCTET_STRING 3 ,
 .Xr ERR_get_error 3
 .Sh BUGS
 .Vt ASN1_OCTET_STRING ,
diff --git a/lib/libcrypto/man/Makefile b/lib/libcrypto/man/Makefile
index 0654dde9c06..42ec3807a2d 100644
--- a/lib/libcrypto/man/Makefile
+++ b/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.110 2017/01/04 21:14:26 schwarze Exp $
+# $OpenBSD: Makefile,v 1.111 2017/01/05 22:38:04 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -229,6 +229,7 @@ MAN=	\
 	crypto.3 \
 	d2i_ASN1_NULL.3 \
 	d2i_ASN1_OBJECT.3 \
+	d2i_ASN1_OCTET_STRING.3 \
 	d2i_ASN1_SEQUENCE_ANY.3 \
 	d2i_AUTHORITY_KEYID.3 \
 	d2i_BASIC_CONSTRAINTS.3 \
diff --git a/lib/libcrypto/man/d2i_ASN1_OCTET_STRING.3 b/lib/libcrypto/man/d2i_ASN1_OCTET_STRING.3
new file mode 100644
index 00000000000..4ea67412d9b
--- /dev/null
+++ b/lib/libcrypto/man/d2i_ASN1_OCTET_STRING.3
@@ -0,0 +1,369 @@
+.\"	$OpenBSD: d2i_ASN1_OCTET_STRING.3,v 1.1 2017/01/05 22:38:04 schwarze Exp $
+.\"
+.\" Copyright (c) 2017 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: January 5 2017 $
+.Dt D2I_ASN1_OCTET_STRING 3
+.Os
+.Sh NAME
+.Nm d2i_ASN1_OCTET_STRING ,
+.Nm i2d_ASN1_OCTET_STRING ,
+.Nm d2i_ASN1_BIT_STRING ,
+.Nm i2d_ASN1_BIT_STRING ,
+.Nm d2i_ASN1_INTEGER ,
+.Nm i2d_ASN1_INTEGER ,
+.Nm d2i_ASN1_ENUMERATED ,
+.Nm i2d_ASN1_ENUMERATED ,
+.Nm d2i_ASN1_UTF8STRING ,
+.Nm i2d_ASN1_UTF8STRING ,
+.Nm d2i_ASN1_IA5STRING ,
+.Nm i2d_ASN1_IA5STRING ,
+.Nm d2i_ASN1_UNIVERSALSTRING ,
+.Nm i2d_ASN1_UNIVERSALSTRING ,
+.Nm d2i_ASN1_BMPSTRING ,
+.Nm i2d_ASN1_BMPSTRING ,
+.Nm d2i_ASN1_GENERALSTRING ,
+.Nm i2d_ASN1_GENERALSTRING ,
+.Nm d2i_ASN1_T61STRING ,
+.Nm i2d_ASN1_T61STRING ,
+.Nm d2i_ASN1_VISIBLESTRING ,
+.Nm i2d_ASN1_VISIBLESTRING ,
+.Nm d2i_ASN1_PRINTABLESTRING ,
+.Nm i2d_ASN1_PRINTABLESTRING ,
+.Nm d2i_ASN1_PRINTABLE ,
+.Nm i2d_ASN1_PRINTABLE ,
+.Nm d2i_DIRECTORYSTRING ,
+.Nm i2d_DIRECTORYSTRING ,
+.Nm d2i_DISPLAYTEXT ,
+.Nm i2d_DISPLAYTEXT ,
+.Nm d2i_ASN1_GENERALIZEDTIME ,
+.Nm i2d_ASN1_GENERALIZEDTIME ,
+.Nm d2i_ASN1_UTCTIME ,
+.Nm i2d_ASN1_UTCTIME ,
+.Nm d2i_ASN1_TIME_new ,
+.Nm i2d_ASN1_TIME_new
+.Nd decode and encode ASN1_STRING objects
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft ASN1_OCTET_STRING *
+.Fo d2i_ASN1_OCTET_STRING
+.Fa "ASN1_OCTET_STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_OCTET_STRING
+.Fa "ASN1_OCTET_STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_BIT_STRING *
+.Fo d2i_ASN1_BIT_STRING
+.Fa "ASN1_BIT_STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_BIT_STRING
+.Fa "ASN1_BIT_STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_INTEGER *
+.Fo d2i_ASN1_INTEGER
+.Fa "ASN1_INTEGER **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_INTEGER
+.Fa "ASN1_INTEGER *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_ENUMERATED *
+.Fo d2i_ASN1_ENUMERATED
+.Fa "ASN1_ENUMERATED **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_ENUMERATED
+.Fa "ASN1_ENUMERATED *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_UTF8STRING *
+.Fo d2i_ASN1_UTF8STRING
+.Fa "ASN1_UTF8STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_UTF8STRING
+.Fa "ASN1_UTF8STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_IA5STRING *
+.Fo d2i_ASN1_IA5STRING
+.Fa "ASN1_IA5STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_IA5STRING
+.Fa "ASN1_IA5STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_UNIVERSALSTRING *
+.Fo d2i_ASN1_UNIVERSALSTRING
+.Fa "ASN1_UNIVERSALSTRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_UNIVERSALSTRING
+.Fa "ASN1_UNIVERSALSTRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_BMPSTRING *
+.Fo d2i_ASN1_BMPSTRING
+.Fa "ASN1_BMPSTRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_BMPSTRING
+.Fa "ASN1_BMPSTRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_GENERALSTRING *
+.Fo d2i_ASN1_GENERALSTRING
+.Fa "ASN1_GENERALSTRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_GENERALSTRING
+.Fa "ASN1_GENERALSTRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_T61STRING *
+.Fo d2i_ASN1_T61STRING
+.Fa "ASN1_T61STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_T61STRING
+.Fa "ASN1_T61STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_VISIBLESTRING *
+.Fo d2i_ASN1_VISIBLESTRING
+.Fa "ASN1_VISIBLESTRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_VISIBLESTRING
+.Fa "ASN1_VISIBLESTRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_PRINTABLESTRING *
+.Fo d2i_ASN1_PRINTABLESTRING
+.Fa "ASN1_PRINTABLESTRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_PRINTABLESTRING
+.Fa "ASN1_PRINTABLESTRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_STRING *
+.Fo d2i_ASN1_PRINTABLE
+.Fa "ASN1_STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_PRINTABLE
+.Fa "ASN1_STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_STRING *
+.Fo d2i_DIRECTORYSTRING
+.Fa "ASN1_STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_DIRECTORYSTRING
+.Fa "ASN1_STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_STRING *
+.Fo d2i_DISPLAYTEXT
+.Fa "ASN1_STRING **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_DISPLAYTEXT
+.Fa "ASN1_STRING *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_GENERALIZEDTIME *
+.Fo d2i_ASN1_GENERALIZEDTIME
+.Fa "ASN1_GENERALIZEDTIME **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_GENERALIZEDTIME
+.Fa "ASN1_GENERALIZEDTIME *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_UTCTIME *
+.Fo d2i_ASN1_UTCTIME
+.Fa "ASN1_UTCTIME **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_UTCTIME
+.Fa "ASN1_UTCTIME *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Ft ASN1_TIME *
+.Fo d2i_ASN1_TIME
+.Fa "ASN1_TIME **val_out"
+.Fa "const unsigned char **der_in"
+.Fa "long length"
+.Fc
+.Ft int
+.Fo i2d_ASN1_TIME
+.Fa "ASN1_TIME *val_in"
+.Fa "unsigned char **der_out"
+.Fc
+.Sh DESCRIPTION
+These functions decode and encode various ASN.1 built-in types
+that can be represented by
+.Vt ASN1_STRING
+objects.
+For details about the semantics, examples, caveats, and bugs, see
+.Xr ASN1_item_d2i 3 .
+.Pp
+The format consists of one identifier octet,
+one or more length octets,
+and one or more content octets.
+The identifier octets and corresponding ASN.1 types are as follows:
+.Bl -column ASN1_GENERALIZEDTIME identifier
+.It Em OpenSSL type Ta Em identifier Ta Em ASN.1 type
+.It Ta
+.It Vt ASN1_OCTET_STRING    Ta 0x04 Ta OCTET STRING
+.It Vt ASN1_BIT_STRING      Ta 0x03 Ta BIT STRING
+.It Vt ASN1_INTEGER         Ta 0x02 Ta INTEGER
+.It Vt ASN1_ENUMERATED      Ta 0x0a Ta ENUMERATED
+.It Vt ASN1_UTF8STRING      Ta 0x0c Ta UTF8String
+.It Vt ASN1_IA5STRING       Ta 0x16 Ta IA5String
+.It Vt ASN1_UNIVERSALSTRING Ta 0x1c Ta UniversalString
+.It Vt ASN1_BMPSTRING       Ta 0x1e Ta BMPString
+.It Vt ASN1_GENERALSTRING   Ta 0x1b Ta GeneralString
+.It Vt ASN1_T61STRING       Ta 0x14 Ta T61String
+.It Vt ASN1_VISIBLESTRING   Ta 0x1a Ta VisibleString
+.It Vt ASN1_PRINTABLESTRING Ta 0x13 Ta PrintableString
+.It Vt ASN1_GENERALIZEDTIME Ta 0x18 Ta GeneralizedTime
+.It Vt ASN1_UTCTIME         Ta 0x17 Ta UTCTime
+.El
+.Pp
+.Fn d2i_DIRECTORYSTRING
+and
+.Fn i2d_DIRECTORYSTRING
+decode and encode an ASN1
+.Vt DirectoryString
+structure defined in RFC 5280 section 4.1.2.4
+and used for ASN.1
+.Vt EDIPartyName
+structures, see
+.Xr EDIPARTYNAME_new 3 .
+When decoding, it accepts any of the types UTF8String, UniversalString,
+BMPString, T61String, or PrintableString.  When encoding, it writes
+out the character string type that is actually passed in.
+.Pp
+.Fn d2i_ASN1_PRINTABLE
+and
+.Fn i2d_ASN1_PRINTABLE
+are non-standard variants of
+.Fn d2i_DIRECTORYSTRING
+and
+.Fn i2d_DIRECTORYSTRING
+that also accept IA5String, NumericString, BIT STRING, and SEQUENCE
+ASN.1 values as well as ASN.1 values with with unknown identifier
+octets (0x07, 0x08, 0x09, 0x0b, 0x0d, 0x0e, 0x0f, 0x1d, and 0x1f).
+Even though the standard requires the use of
+.Vt DirectoryString
+in the relative distinguished names described in
+.Xr X509_NAME_ENTRY_new 3 ,
+the library accepts this wider range of choices.
+.Pp
+.Fn d2i_DISPLAYTEXT
+and
+.Fn i2d_DISPLAYTEXT
+decode and encode an ASN1
+.Vt DisplayText
+structure defined in RFC 5280 section 4.2.1.4
+and used for ASN.1
+.Vt UserNotice
+structures in certificate policies, see
+.Xr USERNOTICE_new 3 .
+When decoding, it accepts any of the types UTF8String, IA5String,
+BMPString, or VisibleString.  When encoding, it writes out the
+character string type that is actually passed in.
+.Pp
+.Fn d2i_ASN1_TIME
+and
+.Fn i2d_ASN1_TIME
+decode and encode an ASN1
+.Vt Time
+structure defined in RFC 5280 section 4.1
+and used for ASN.1
+.Vt Validity
+structures in certificates, see
+.Xr X509_VAL_new 3 ,
+and also used for certificate revocation lists, see
+.Xr X509_CRL_INFO_new 3 .
+When decoding, it accepts either GeneralizedTime or UTCTime.
+When encoding, it writes out the time type that is actually passed in.
+.Sh RETURN VALUES
+The
+.Fn d2i_*
+decoding functions return an
+.Vt ASN1_STRING
+object or
+.Dv NULL
+if an error occurs.
+.Pp
+The
+.Fn i2d_*
+encoding functions return the number of bytes successfully encoded
+or a negative value if an error occurs.
+.Sh SEE ALSO
+.Xr ASN1_item_d2i 3 ,
+.Xr ASN1_STRING_new 3
+.Sh STANDARDS
+ITU-T Recommendation X.680, also known as ISO/IEC 8824-1:
+Information technology - Abstract Syntax Notation One (ASN.1):
+Specification of basic notation
+.Pp
+RFC 5280: Internet X.509 Public Key Infrastructure Certificate and
+Certificate Revocation List (CRL) Profile