path: root/lib/libutil/ober_add_string.3

.\" $OpenBSD: ober_add_string.3,v 1.2 2020/10/16 09:29:04 jmc Exp $
.\"
.\" Copyright (c) 2007, 2012 Reyk Floeter <reyk@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: October 16 2020 $
.Dt OBER_ADD_STRING 3
.Os
.Sh NAME
.Nm ober_get_element ,
.Nm ober_add_sequence ,
.Nm ober_add_set ,
.Nm ober_add_null ,
.Nm ober_add_eoc ,
.Nm ober_add_integer ,
.Nm ober_add_enumerated ,
.Nm ober_add_boolean ,
.Nm ober_add_string ,
.Nm ober_add_nstring ,
.Nm ober_add_ostring ,
.Nm ober_add_bitstring ,
.Nm ober_add_oid ,
.Nm ober_add_noid ,
.Nm ober_add_oidstring ,
.Nm ober_printf_elements
.Nd create ASN.1 objects for BER encoding
.Sh SYNOPSIS
.In sys/types.h
.In ber.h
.Ft "struct ber_element *"
.Fn "ober_get_element" "unsigned int encoding"
.Ft "struct ber_element *"
.Fn "ober_add_sequence" "struct ber_element *prev"
.Ft "struct ber_element *"
.Fn "ober_add_set" "struct ber_element *prev"
.Ft "struct ber_element *"
.Fn "ober_add_null" "struct ber_element *prev"
.Ft "struct ber_element *"
.Fn "ober_add_eoc" "struct ber_element *prev"
.Ft "struct ber_element *"
.Fn "ober_add_integer" "struct ber_element *prev" "long long val"
.Ft "struct ber_element *"
.Fn "ober_add_enumerated" "struct ber_element *prev" "long long val"
.Ft "struct ber_element *"
.Fn "ober_add_boolean" "struct ber_element *prev" "int bool"
.Ft "struct ber_element *"
.Fn "ober_add_string" "struct ber_element *prev" "const char *string"
.Ft "struct ber_element *"
.Fn "ober_add_nstring" "struct ber_element *prev" "const char *string" "size_t size"
.Ft "struct ber_element *"
.Fo "ober_add_ostring"
.Fa "struct ber_element *prev"
.Fa "struct ber_octetstring *ostring"
.Fc
.Ft "struct ber_element *"
.Fo "ober_add_bitstring"
.Fa "struct ber_element *prev"
.Fa "const void *buf"
.Fa "size_t size"
.Fc
.Ft "struct ber_element *"
.Fn "ober_add_oid" "struct ber_element *prev" "struct ber_oid *oid"
.Ft "struct ber_element *"
.Fn "ober_add_noid" "struct ber_element *prev" "struct ber_oid *oid" "int n"
.Ft "struct ber_element *"
.Fn "ober_add_oidstring" "struct ber_element *prev" "const char *string"
.Ft "struct ber_element *"
.Fn "ober_printf_elements" "struct ber_element *prev" "char *format" "..."
.Sh DESCRIPTION
Intermediary storage of BER elements during encoding and decoding uses the
following structure:
.Bd -literal
struct ber_element {
	struct ber_element	*be_next;
	unsigned int		 be_type;
	unsigned int		 be_encoding;
	size_t			 be_len;
	off_t			 be_offs;
	int			 be_free;
	u_int8_t		 be_class;
	void			(*be_cb)(void *, size_t);
	void			*be_cbarg;
	union {
		struct ber_element	*bv_sub;
		void			*bv_val;
		long long		 bv_numeric;
	} be_union;
#define be_sub		be_union.bv_sub
#define be_val		be_union.bv_val
#define be_numeric	be_union.bv_numeric
};
.Ed
.Pp
.Fn ober_get_element
creates a new
.Vt ber_element
with default values, dynamically allocates required storage, and sets
.Fa be_encoding
to
.Fa encoding .
.Pp
The
.Fn ober_add_*
functions allocate a new
.Vt ber_element
of the respective type.
If
.Fa prev
is an empty sequence or set, they put the new element into that
sequence or set.
Otherwise, unless
.Fa prev
is
.Dv NULL ,
they put it behind
.Fa prev .
Those functions taking a second argument initialize the content
of the new element from the second argument.
.Pp
.Fn ober_printf_elements
creates zero or more
.Vt ber_element
structures.
For each byte in
.Fa fmt ,
arguments of the types given in the following table are consumed
and passed to the listed function, creating one
.Vt ber_element
per byte.
The following bytes are valid:
.Bl -column -offset indent byte ober_add_enumerated "struct ber_element *"
.It Sy byte Ta Sy function Ta Sy arguments
.It B   Ta Fn ober_add_bitstring  Ta 2: Vt void * , size_t
.It b   Ta Fn ober_add_boolean    Ta 1: Vt int
.It d   Ta Fn ober_add_integer    Ta 1: Vt int
.It E   Ta Fn ober_add_enumerated Ta 1: Vt long long
.It e   Ta see below              Ta 1: Vt struct ber_element *
.It i   Ta Fn ober_add_integer    Ta 1: Vt long long
.It O   Ta Fn ober_add_oid        Ta 1: Vt struct ber_oid *
.It o   Ta Fn ober_add_oidstring  Ta 1: Vt char *
.It s   Ta Fn ober_add_string     Ta 1: Vt char *
.It t   Ta Xr ober_set_header 3   Ta 2: Vt int , unsigned int
.It x   Ta Fn ober_add_nstring    Ta 2: Vt char * , size_t
.It \&( Ta Fn ober_add_set        Ta 0
.It \&) Ta see below              Ta 0
.It \&. Ta Fn ober_add_eoc        Ta 0
.It 0   Ta Fn ober_add_null       Ta 0
.It {   Ta Fn ober_add_sequence   Ta 0
.It }   Ta see below              Ta 0
.El
.Pp
The
.Sq e
and
.Sq t
bytes are special in so far as they do not create new elements.
The
.Sq e
byte adds an element that was already created earlier into or behind
the previous element, or into and behind
.Fa ber
if the
.Sq e
is the first byte in
.Fa fmt ,
just like the
.Fn ober_add_*
functions would add a new element.
The
.Sq t
byte changes the class and type of the last element, or of
.Fa ber
if
.Sq t
is the first byte in
.Fa fmt ,
without changing its position relative to other elements.
.Pp
A closing brace or parenthesis closes an open sequence or set,
if any, such that the next element will be added behind rather
than into the sequence or set.
Only one sequence or set can be open at any time.
Nesting is not supported without multiple function calls.
.Sh RETURN VALUES
Upon successful completion,
these functions return a pointer to a populated
.Vt ber_element .
Otherwise
.Dv NULL
is returned and the global variable
.Va errno
is set to indicate the error.
.Pp
.Fn ober_printf_elements
returns
.Dv NULL
without setting
.Va errno
if
.Fa fmt
is an empty string and
.Fa ber
is
.Dv NULL .
.Sh SEE ALSO
.Xr ober_get_string 3 ,
.Xr ober_oid_cmp 3 ,
.Xr ober_read_elements 3 ,
.Xr ober_set_header 3
.Sh STANDARDS
ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
Information technology - ASN.1 encoding rules.
.Sh HISTORY
These functions first appeared as internal functions in
.Xr snmpd 8
in
.Ox 4.2
and were moved to libutil in
.Ox 6.6 .
.Sh AUTHORS
.An -nosplit
The BER library was written by
.An Claudio Jeker Aq Mt claudio@openbsd.org ,
.An Marc Balmer Aq Mt marc@openbsd.org
and
.An Reyk Floeter Aq Mt reyk@openbsd.org .