1.\" $OpenBSD: ober_add_string.3,v 1.2 2020/10/16 09:29:04 jmc Exp $ 2.\" 3.\" Copyright (c) 2007, 2012 Reyk Floeter <reyk@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: October 16 2020 $ 18.Dt OBER_ADD_STRING 3 19.Os 20.Sh NAME 21.Nm ober_get_element , 22.Nm ober_add_sequence , 23.Nm ober_add_set , 24.Nm ober_add_null , 25.Nm ober_add_eoc , 26.Nm ober_add_integer , 27.Nm ober_add_enumerated , 28.Nm ober_add_boolean , 29.Nm ober_add_string , 30.Nm ober_add_nstring , 31.Nm ober_add_ostring , 32.Nm ober_add_bitstring , 33.Nm ober_add_oid , 34.Nm ober_add_noid , 35.Nm ober_add_oidstring , 36.Nm ober_printf_elements 37.Nd create ASN.1 objects for BER encoding 38.Sh SYNOPSIS 39.In sys/types.h 40.In ber.h 41.Ft "struct ber_element *" 42.Fn "ober_get_element" "unsigned int encoding" 43.Ft "struct ber_element *" 44.Fn "ober_add_sequence" "struct ber_element *prev" 45.Ft "struct ber_element *" 46.Fn "ober_add_set" "struct ber_element *prev" 47.Ft "struct ber_element *" 48.Fn "ober_add_null" "struct ber_element *prev" 49.Ft "struct ber_element *" 50.Fn "ober_add_eoc" "struct ber_element *prev" 51.Ft "struct ber_element *" 52.Fn "ober_add_integer" "struct ber_element *prev" "long long val" 53.Ft "struct ber_element *" 54.Fn "ober_add_enumerated" "struct ber_element *prev" "long long val" 55.Ft "struct ber_element *" 56.Fn "ober_add_boolean" "struct ber_element *prev" "int bool" 57.Ft "struct ber_element *" 58.Fn "ober_add_string" "struct ber_element *prev" "const char *string" 59.Ft "struct ber_element *" 60.Fn "ober_add_nstring" "struct ber_element *prev" "const char *string" "size_t size" 61.Ft "struct ber_element *" 62.Fo "ober_add_ostring" 63.Fa "struct ber_element *prev" 64.Fa "struct ber_octetstring *ostring" 65.Fc 66.Ft "struct ber_element *" 67.Fo "ober_add_bitstring" 68.Fa "struct ber_element *prev" 69.Fa "const void *buf" 70.Fa "size_t size" 71.Fc 72.Ft "struct ber_element *" 73.Fn "ober_add_oid" "struct ber_element *prev" "struct ber_oid *oid" 74.Ft "struct ber_element *" 75.Fn "ober_add_noid" "struct ber_element *prev" "struct ber_oid *oid" "int n" 76.Ft "struct ber_element *" 77.Fn "ober_add_oidstring" "struct ber_element *prev" "const char *string" 78.Ft "struct ber_element *" 79.Fn "ober_printf_elements" "struct ber_element *prev" "char *format" "..." 80.Sh DESCRIPTION 81Intermediary storage of BER elements during encoding and decoding uses the 82following structure: 83.Bd -literal 84struct ber_element { 85 struct ber_element *be_next; 86 unsigned int be_type; 87 unsigned int be_encoding; 88 size_t be_len; 89 off_t be_offs; 90 int be_free; 91 u_int8_t be_class; 92 void (*be_cb)(void *, size_t); 93 void *be_cbarg; 94 union { 95 struct ber_element *bv_sub; 96 void *bv_val; 97 long long bv_numeric; 98 } be_union; 99#define be_sub be_union.bv_sub 100#define be_val be_union.bv_val 101#define be_numeric be_union.bv_numeric 102}; 103.Ed 104.Pp 105.Fn ober_get_element 106creates a new 107.Vt ber_element 108with default values, dynamically allocates required storage, and sets 109.Fa be_encoding 110to 111.Fa encoding . 112.Pp 113The 114.Fn ober_add_* 115functions allocate a new 116.Vt ber_element 117of the respective type. 118If 119.Fa prev 120is an empty sequence or set, they put the new element into that 121sequence or set. 122Otherwise, unless 123.Fa prev 124is 125.Dv NULL , 126they put it behind 127.Fa prev . 128Those functions taking a second argument initialize the content 129of the new element from the second argument. 130.Pp 131.Fn ober_printf_elements 132creates zero or more 133.Vt ber_element 134structures. 135For each byte in 136.Fa fmt , 137arguments of the types given in the following table are consumed 138and passed to the listed function, creating one 139.Vt ber_element 140per byte. 141The following bytes are valid: 142.Bl -column -offset indent byte ober_add_enumerated "struct ber_element *" 143.It Sy byte Ta Sy function Ta Sy arguments 144.It B Ta Fn ober_add_bitstring Ta 2: Vt void * , size_t 145.It b Ta Fn ober_add_boolean Ta 1: Vt int 146.It d Ta Fn ober_add_integer Ta 1: Vt int 147.It E Ta Fn ober_add_enumerated Ta 1: Vt long long 148.It e Ta see below Ta 1: Vt struct ber_element * 149.It i Ta Fn ober_add_integer Ta 1: Vt long long 150.It O Ta Fn ober_add_oid Ta 1: Vt struct ber_oid * 151.It o Ta Fn ober_add_oidstring Ta 1: Vt char * 152.It s Ta Fn ober_add_string Ta 1: Vt char * 153.It t Ta Xr ober_set_header 3 Ta 2: Vt int , unsigned int 154.It x Ta Fn ober_add_nstring Ta 2: Vt char * , size_t 155.It \&( Ta Fn ober_add_set Ta 0 156.It \&) Ta see below Ta 0 157.It \&. Ta Fn ober_add_eoc Ta 0 158.It 0 Ta Fn ober_add_null Ta 0 159.It { Ta Fn ober_add_sequence Ta 0 160.It } Ta see below Ta 0 161.El 162.Pp 163The 164.Sq e 165and 166.Sq t 167bytes are special in so far as they do not create new elements. 168The 169.Sq e 170byte adds an element that was already created earlier into or behind 171the previous element, or into and behind 172.Fa ber 173if the 174.Sq e 175is the first byte in 176.Fa fmt , 177just like the 178.Fn ober_add_* 179functions would add a new element. 180The 181.Sq t 182byte changes the class and type of the last element, or of 183.Fa ber 184if 185.Sq t 186is the first byte in 187.Fa fmt , 188without changing its position relative to other elements. 189.Pp 190A closing brace or parenthesis closes an open sequence or set, 191if any, such that the next element will be added behind rather 192than into the sequence or set. 193Only one sequence or set can be open at any time. 194Nesting is not supported without multiple function calls. 195.Sh RETURN VALUES 196Upon successful completion, 197these functions return a pointer to a populated 198.Vt ber_element . 199Otherwise 200.Dv NULL 201is returned and the global variable 202.Va errno 203is set to indicate the error. 204.Pp 205.Fn ober_printf_elements 206returns 207.Dv NULL 208without setting 209.Va errno 210if 211.Fa fmt 212is an empty string and 213.Fa ber 214is 215.Dv NULL . 216.Sh SEE ALSO 217.Xr ober_get_string 3 , 218.Xr ober_oid_cmp 3 , 219.Xr ober_read_elements 3 , 220.Xr ober_set_header 3 221.Sh STANDARDS 222ITU-T Recommendation X.690, also known as ISO/IEC 8825-1: 223Information technology - ASN.1 encoding rules. 224.Sh HISTORY 225These functions first appeared as internal functions in 226.Xr snmpd 8 227in 228.Ox 4.2 229and were moved to libutil in 230.Ox 6.6 . 231.Sh AUTHORS 232.An -nosplit 233The BER library was written by 234.An Claudio Jeker Aq Mt claudio@openbsd.org , 235.An Marc Balmer Aq Mt marc@openbsd.org 236and 237.An Reyk Floeter Aq Mt reyk@openbsd.org . 238