Attached is a manpage for ASN1_get_object(3), ASN1_put_object(3), and
ASN1_put_eoc(3). Having the first function documented would have saved
me a lot of time. (I did the others for symmetry.)
In short, they encode or decode ASN.1 data structures from/into a
buffer. Using the first, one can very easily take a BER-encoded string
and parse out its ASN.1 data structures.
The functions are defined in /usr/src/lib/libcrypto/asn1/asn1_lib.c.
.\" $OpenBSD: mdoc.template,v 1.15 2014/03/31 00:09:54 dlg Exp $
.\"
.\" Copyright (c) 2019 Kristaps Dzonsons <krist...@bsd.lv>
.\"
.\" 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$
.Dt ASN1_GET_OBJECT 3
.Os
.Sh NAME
.Nm ASN1_get_object ,
.Nm ASN1_put_eoc ,
.Nm ASN1_put_object
.Nd encode and decode ASN.1 data structures
.Sh SYNOPSIS
.In openssl/asn1.h
.Ft int
.Fo ASN1_get_object
.Fa "const unsigned char **in"
.Fa "long *len"
.Fa "int *tag"
.Fa "int *class"
.Fa "long insize"
.Fc
.Ft int
.Fo ASN1_put_eoc
.Fa "unsigned char **out"
.Fc
.Ft void
.Fo ASN1_put_object
.Fa "unsigned char **out"
.Fa "int constructed"
.Fa "int length"
.Fa "int tag"
.Fa "int class"
.Fc
.Sh DESCRIPTION
.Fn ASN1_get_object
decodes an ASN.1 data structure from a BER-encoded string
.Fa in
of length
.Fa insize .
.Pp
On success,
.Fn ASN1_get_object
encodes the data structure's content length in
.Fa len ,
the content identifier in
.Fa tag ,
ASN.1 class in
.Fa class ,
and other pertinent bits in the return value.
The
.Fa in
pointer is set to the first byte of the content data.
.Pp
The
.Fa class
describes the type of content data.
It contains the
.Dv V_ASN1_PRIVATE
bit to indicate a non-native type for
.Fa tag .
Otherwise, the
.Fa tag
will be one of
.Dv V_ASN1_INTEGER ,
.Dv V_ASN1_BIT_STRING ,
or any other ASN.1 native types defined in
.Pa openssl/asn1.h .
.Pp
.Fn ASN1_put_object
encodes an ASN.1 data structure identified by
.Fa tag
into the buffer
.Fa pp ,
which must be correctly-sized by the caller.
If
.Fa class
contains the
.Dv V_ASN1_PRIVATE
bit, the type is non-native.
Otherwise the
.Fa tag
must be one of
.Dv V_ASN1_INTEGER ,
.Dv V_ASN1_BIT_STRING ,
or any other ASN.1 native type defined in
.Pa openssl/asn.1 .
.Pp
If
.Fa constructured
is non-zero, the data structure is constructed.
If if is
.Li 0x02 ,
the data structure is constructed and of indefinite length.
In the latter case,
.Fa length
argument is ignored and the data structure is set to indefinite length.
Data structures of indefinite length must invoke
.Fn ASN1_put_eoc
after serialising data.
.Pp
Otherwise, if
.Fa constructed
is not
.Li 0x02 ,
the data structure is encoded with the given
.Fa length .
.Pp
The
.Fa out
pointer is set to the first byte of the content data.
.Pp
The
.Fn ASN1_put_eoc
function terminates an indefinite-length data structure started by
.Fn ASN1_put_object
with a
.Fa constructed
value of
.Li 0x02 .
.\" The following requests should be uncommented and used where appropriate.
.\" .Sh CONTEXT
.\" For section 9 functions only.
.Sh RETURN VALUES
.Fn ASN1_get_object
returns a bit field.
If
.Li 0x80
is set, the conversion failed.
Any other bits indicate that the data structure was constructed with
indefinite length.
.Pp
Most callers should check for the generic error condition.
If the error bit is set,
.Fa len ,
.Fa tag ,
.Fa class ,
and
.Fa in
contained undefined values.
.Pp
.Fn ASN1_put_eoc
always returns
.Li 0x02 .
.\" For sections 2, 3, and 9 function return values only.
.\" .Sh ENVIRONMENT
.\" For sections 1, 6, 7, and 8 only.
.\" .Sh FILES
.\" .Sh EXIT STATUS
.\" For sections 1, 6, and 8 only.
.Sh EXAMPLES
The following converts an X509 extension
.Fa ext
to a DER-encoded string and examines the extension's top-level data
structure.
On success, and if the data structure is a native ASN.1 sequence, it
invokes
.Fn do_something
with the BER-encoded data structure and length as arguments.
.Bd -literal
int dsz, ptag, pclass;
unsigned char *d;
long plen;
if ((dsz = i2d_X509_EXTENSION(ext, &d)) < 0)
return 0;
if (0x80 & ASN1_get_object(&d, &plen, &ptag, &pclass, dsz))
return 0;
if (pclass || V_ASN1_SEQUENCE != ptag)
return 0;
return do_something(d, plen);
.Ed
.\" .Sh DIAGNOSTICS
.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
.\" .Sh ERRORS
.\" For sections 2, 3, 4, and 9 errno settings only.
.\" .Sh SEE ALSO
.\" .Sh STANDARDS
.\" .Sh HISTORY
.\" .Sh AUTHORS
.\" .Sh CAVEATS
.\" .Sh BUGS
