document ASN1_put_object(3) and ASN1_put_eoc(3)

3 files changed, 186 insertions, 3 deletions

diff --git a/src/lib/libcrypto/man/ASN1_TYPE_get.3 b/src/lib/libcrypto/man/ASN1_TYPE_get.3
index 3d6ad0bc63..a31f762335 100644
--- a/src/lib/libcrypto/man/ASN1_TYPE_get.3
+++ b/src/lib/libcrypto/man/ASN1_TYPE_get.3
@@ -1,4 +1,4 @@
-.\"     $OpenBSD: ASN1_TYPE_get.3,v 1.10 2019/06/10 09:49:48 schwarze Exp $
+.\"     $OpenBSD: ASN1_TYPE_get.3,v 1.11 2019/08/26 11:41:31 schwarze Exp $
 .\"     OpenSSL 99d63d46 Mon Jun 6 00:43:05 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: June 10 2019 $
+.Dd $Mdocdate: August 26 2019 $
 .Dt ASN1_TYPE_GET 3
 .Os
 .Sh NAME
@@ -277,6 +277,7 @@ returns 0 for a match or non-zero for a mismatch.
 .Xr ASN1_generate_nconf 3 ,
 .Xr ASN1_item_free 3 ,
 .Xr ASN1_OBJECT_new 3 ,
+.Xr ASN1_put_object 3 ,
 .Xr ASN1_STRING_dup 3 ,
 .Xr ASN1_STRING_new 3 ,
 .Xr crypto 3 ,
diff --git a/src/lib/libcrypto/man/ASN1_put_object.3 b/src/lib/libcrypto/man/ASN1_put_object.3
new file mode 100644
index 0000000000..f1f0021fe5
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_put_object.3
@@ -0,0 +1,181 @@
+.\" $OpenBSD: ASN1_put_object.3,v 1.1 2019/08/26 11:41:31 schwarze Exp $
+.\"
+.\" Copyright (c) 2019 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: August 26 2019 $
+.Dt ASN1_PUT_OBJECT 3
+.Os
+.Sh NAME
+.Nm ASN1_put_object ,
+.Nm ASN1_put_eoc
+.Nd start and end the BER encoding of an arbitrary ASN.1 data element
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft void
+.Fo ASN1_put_object
+.Fa "unsigned char **ber_out"
+.Fa "int constructed"
+.Fa "int length"
+.Fa "int tag"
+.Fa "int class"
+.Fc
+.Ft int
+.Fo ASN1_put_eoc
+.Fa "unsigned char **ber_out"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_put_object
+begins writing the BER encoding of an arbitrary ASN.1 data element
+to the buffer
+.Pf * ber_out
+by writing the identifier and the length bytes.
+Making sure that there is sufficient space in the buffer
+is the responsibility of the caller.
+This function does not write any content bytes
+nor any end-of-content bytes.
+.Pp
+The tag
+.Fa class
+can be
+.Dv V_ASN1_UNIVERSAL ,
+.Dv V_ASN1_APPLICATION ,
+.Dv V_ASN1_CONTEXT_SPECIFIC ,
+or
+.Dv V_ASN1_PRIVATE
+and is written to the two most significant bits of the first byte written.
+.Pp
+The
+.Fa constructed
+argument can have the following values:
+.Bl -tag -width 1n -offset 2n -compact
+.It 0
+Start a primitive value by setting the third most significant bit
+of the first byte written to 0.
+Always use the definite form.
+.It 1
+Start a constructed value by setting the third most significant bit
+of the first byte written to 1, and use the definite form.
+.It 2
+Start a constructed value and use the indefinite form,
+.El
+.Pp
+If the
+.Fa tag
+is less than 0x1f, it is written to the five least significant bits
+of the only identifier byte written.
+Otherwise, these five bits are all set to 1, and the
+.Fa tag
+is encoded in one or more following identifier bytes as needed.
+.Pp
+After completing the identifier byte(s),
+when using the definite form, the given
+.Fa length
+is encoded in one or more bytes as needed.
+Otherwise, the special byte 0x80 is written instead and the
+.Ar length
+argument is ignored.
+.Pp
+At the end,
+.Pf * Fa ber_out
+is set to the byte following the last byte written.
+The calling code can then start writing content bytes.
+.Pp
+If the indefinite form was selected,
+the calling code is also responsible for calling
+.Fn ASN1_put_eoc
+which writes an end-of-content marker to
+.Pf * Fa ber_out ,
+consisting of two NUL bytes, and advances
+.Pf * Fa ber_out
+by two bytes.
+.Sh RETURN VALUES
+.Fn ASN1_put_eoc
+returns the number of bytes written, which is always 2.
+.Sh SEE ALSO
+.Xr ASN1_item_i2d 3 ,
+.Xr ASN1_TYPE_get 3 ,
+.Xr i2d_ASN1_NULL 3 ,
+.Xr i2d_ASN1_OBJECT 3 ,
+.Xr i2d_ASN1_OCTET_STRING 3 ,
+.Xr i2d_ASN1_SEQUENCE_ANY 3
+.Sh HISTORY
+.Fn ASN1_put_object
+first appeared in SSLeay 0.5.1 and has been available since
+.Ox 2.4 .
+.Pp
+.Fn ASN1_put_eoc
+first appeared in OpenSSL 0.9.8 and has been available since
+.Ox 4.5 .
+.Sh CAVEATS
+Neither
+.Fn ASN1_put_object
+nor
+.Fn ASN1_put_eoc
+do any sanity checking.
+When called in inconsistent ways, invalid content may result in
+.Pf * Fa ber_out ,
+for example
+.Bl -dash -compact
+.It
+a
+.Fa tag
+number less than 0x1f with a non-universal
+.Fa class
+.It
+a
+.Fa tag
+number equal to 0x00 or 0x1f
+.It
+a
+.Vt BOOLEAN ,
+.Vt INTEGER ,
+.Vt NULL
+etc. with the
+.Fa constructed
+bit set
+.It
+a
+.Vt SEQUENCE
+or
+.Vt SET
+etc. without the
+.Fa constructed
+bit set
+.It
+a
+.Fa length
+that makes no sense for the given
+.Fa tag
+.It
+a
+.Fa length
+that disagrees with the following data
+.It
+a
+.Vt BOOLEAN ,
+.Vt INTEGER ,
+.Vt NULL
+etc. in indefinite form
+.It
+an end-of-content marker even though no indefinite form was started
+.It
+\&...
+.El
+.Pp
+If the calling code wants to find out how many bytes were written,
+it needs to save a copy of the pointer
+.Pf * Fa ber_out
+before calling
+.Fn ASN1_put_object .
diff --git a/src/lib/libcrypto/man/Makefile b/src/lib/libcrypto/man/Makefile
index e3e8e710c2..2938a65cda 100644
--- a/src/lib/libcrypto/man/Makefile
+++ b/src/lib/libcrypto/man/Makefile
@@ -1,4 +1,4 @@
-# $OpenBSD: Makefile,v 1.156 2019/08/25 17:08:20 schwarze Exp $
+# $OpenBSD: Makefile,v 1.157 2019/08/26 11:41:31 schwarze Exp $
 
 .include <bsd.own.mk>
 
@@ -15,6 +15,7 @@ MAN=	\
         ASN1_generate_nconf.3 \
         ASN1_item_d2i.3 \
         ASN1_item_new.3 \
+        ASN1_put_object.3 \
         ASN1_time_parse.3 \
         AUTHORITY_KEYID_new.3 \
         BASIC_CONSTRAINTS_new.3 \