document ASN1_put_object(3) and ASN1_put_eoc(3)

1 files changed, 181 insertions, 0 deletions

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 .