OBER_ADD_STRING(3) Library Functions Manual OBER_ADD_STRING(3)

ober_get_element, ober_add_sequence, ober_add_set, ober_add_null, ober_add_eoc, ober_add_integer, ober_add_enumerated, ober_add_boolean, ober_add_string, ober_add_nstring, ober_add_ostring, ober_add_bitstring, ober_add_oid, ober_add_noid, ober_add_oidstring, ober_printf_elements — create ASN.1 objects for BER encoding

#include <sys/types.h>
#include <ber.h>

struct ber_element *
ober_get_element(unsigned int encoding);

struct ber_element *
ober_add_sequence(struct ber_element *prev);

struct ber_element *
ober_add_set(struct ber_element *prev);

struct ber_element *
ober_add_null(struct ber_element *prev);

struct ber_element *
ober_add_eoc(struct ber_element *prev);

struct ber_element *
ober_add_integer(struct ber_element *prev, long long val);

struct ber_element *
ober_add_enumerated(struct ber_element *prev, long long val);

struct ber_element *
ober_add_boolean(struct ber_element *prev, int bool);

struct ber_element *
ober_add_string(struct ber_element *prev, const char *string);

struct ber_element *
ober_add_nstring(struct ber_element *prev, const char *string, size_t size);

struct ber_element *
ober_add_ostring(struct ber_element *prev, struct ber_octetstring *ostring);

struct ber_element *
ober_add_bitstring(struct ber_element *prev, const void *buf, size_t size);

struct ber_element *
ober_add_oid(struct ber_element *prev, struct ber_oid *oid);

struct ber_element *
ober_add_noid(struct ber_element *prev, struct ber_oid *oid, int n);

struct ber_element *
ober_add_oidstring(struct ber_element *prev, const char *string);

struct ber_element *
ober_printf_elements(struct ber_element *prev, char *format, ...);

Intermediary storage of BER elements during encoding and decoding uses the following structure:

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
};

() creates a new ber_element with default values, dynamically allocates required storage, and sets be_encoding to encoding.

The () functions allocate a new ber_element of the respective type. If prev is an empty sequence or set, they put the new element into that sequence or set. Otherwise, unless prev is NULL, they put it behind prev. Those functions taking a second argument initialize the content of the new element from the second argument.

() creates zero or more ber_element structures. For each byte in fmt, arguments of the types given in the following table are consumed and passed to the listed function, creating one ber_element per byte. The following bytes are valid:

B () 2: void *, size_t
b () 1: int
d () 1: int
E () 1: long long
e see below 1: struct ber_element *
i ober_add_integer() 1: long long
O () 1: struct ber_oid *
o () 1: char *
s () 1: char *
t ober_set_header(3) 2: int, unsigned int
x () 2: char *, size_t
( () 0
) see below 0
. () 0
0 () 0
{ () 0
} see below 0

The ‘e’ and ‘t’ bytes are special in so far as they do not create new elements. The ‘e’ byte adds an element that was already created earlier into or behind the previous element, or into and behind ber if the ‘e’ is the first byte in fmt, just like the () functions would add a new element. The ‘t’ byte changes the class and type of the last element, or of ber if ‘t’ is the first byte in fmt, without changing its position relative to other elements.

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.

Upon successful completion, these functions return a pointer to a populated ber_element. Otherwise NULL is returned and the global variable errno is set to indicate the error.

ober_printf_elements() returns NULL without setting errno if fmt is an empty string and ber is NULL.

ober_get_string(3), ober_oid_cmp(3), ober_read_elements(3), ober_set_header(3)

ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: Information technology - ASN.1 encoding rules.

These functions first appeared as internal functions in snmpd(8) in OpenBSD 4.2 and were moved to libutil in OpenBSD 6.6.

The BER library was written by Claudio Jeker <claudio@openbsd.org>, Marc Balmer <marc@openbsd.org> and Reyk Floeter <reyk@openbsd.org>.

October 16, 2020 OpenBSD 7.6