jcs.org
jcs's openbsd hax
openbsd
1.\" $OpenBSD: ober_add_string.3,v 1.4 2025/06/13 18:34:00 schwarze 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: June 13 2025 $
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.Lb libutil
40.In sys/types.h
41.In ber.h
42.Ft struct ber_element *
43.Fn "ober_get_element" "unsigned int encoding"
44.Ft struct ber_element *
45.Fn "ober_add_sequence" "struct ber_element *prev"
46.Ft struct ber_element *
47.Fn "ober_add_set" "struct ber_element *prev"
48.Ft struct ber_element *
49.Fn "ober_add_null" "struct ber_element *prev"
50.Ft struct ber_element *
51.Fn "ober_add_eoc" "struct ber_element *prev"
52.Ft struct ber_element *
53.Fn "ober_add_integer" "struct ber_element *prev" "long long val"
54.Ft struct ber_element *
55.Fn "ober_add_enumerated" "struct ber_element *prev" "long long val"
56.Ft struct ber_element *
57.Fn "ober_add_boolean" "struct ber_element *prev" "int bool"
58.Ft struct ber_element *
59.Fn "ober_add_string" "struct ber_element *prev" "const char *string"
60.Ft struct ber_element *
61.Fn "ober_add_nstring" "struct ber_element *prev" "const char *string" "size_t size"
62.Ft struct ber_element *
63.Fo "ober_add_ostring"
64.Fa "struct ber_element *prev"
65.Fa "struct ber_octetstring *ostring"
66.Fc
67.Ft struct ber_element *
68.Fo "ober_add_bitstring"
69.Fa "struct ber_element *prev"
70.Fa "const void *buf"
71.Fa "size_t size"
72.Fc
73.Ft struct ber_element *
74.Fn "ober_add_oid" "struct ber_element *prev" "struct ber_oid *oid"
75.Ft struct ber_element *
76.Fn "ober_add_noid" "struct ber_element *prev" "struct ber_oid *oid" "int n"
77.Ft struct ber_element *
78.Fn "ober_add_oidstring" "struct ber_element *prev" "const char *string"
79.Ft struct ber_element *
80.Fn "ober_printf_elements" "struct ber_element *prev" "char *format" "..."
81.Sh DESCRIPTION
82Intermediary storage of BER elements during encoding and decoding uses the
83following structure:
84.Bd -literal
85struct ber_element {
86 struct ber_element *be_next;
87 unsigned int be_type;
88 unsigned int be_encoding;
89 size_t be_len;
90 off_t be_offs;
91 int be_free;
92 u_int8_t be_class;
93 void (*be_cb)(void *, size_t);
94 void *be_cbarg;
95 union {
96 struct ber_element *bv_sub;
97 void *bv_val;
98 long long bv_numeric;
99 } be_union;
100#define be_sub be_union.bv_sub
101#define be_val be_union.bv_val
102#define be_numeric be_union.bv_numeric
103};
104.Ed
105.Pp
106.Fn ober_get_element
107creates a new
108.Vt ber_element
109with default values, dynamically allocates required storage, and sets
110.Fa be_encoding
111to
112.Fa encoding .
113.Pp
114The
115.Fn ober_add_*
116functions allocate a new
117.Vt ber_element
118of the respective type.
119If
120.Fa prev
121is an empty sequence or set, they put the new element into that
122sequence or set.
123Otherwise, unless
124.Fa prev
125is
126.Dv NULL ,
127they put it behind
128.Fa prev .
129Those functions taking a second argument initialize the content
130of the new element from the second argument.
131.Pp
132.Fn ober_printf_elements
133creates zero or more
134.Vt ber_element
135structures.
136For each byte in
137.Fa fmt ,
138arguments of the types given in the following table are consumed
139and passed to the listed function, creating one
140.Vt ber_element
141per byte.
142The following bytes are valid:
143.Bl -column -offset indent byte ober_add_enumerated "struct ber_element *"
144.It Sy byte Ta Sy function Ta Sy arguments
145.It B Ta Fn ober_add_bitstring Ta 2: Vt void * , size_t
146.It b Ta Fn ober_add_boolean Ta 1: Vt int
147.It d Ta Fn ober_add_integer Ta 1: Vt int
148.It E Ta Fn ober_add_enumerated Ta 1: Vt long long
149.It e Ta see below Ta 1: Vt struct ber_element *
150.It i Ta Fn ober_add_integer Ta 1: Vt long long
151.It O Ta Fn ober_add_oid Ta 1: Vt struct ber_oid *
152.It o Ta Fn ober_add_oidstring Ta 1: Vt char *
153.It s Ta Fn ober_add_string Ta 1: Vt char *
154.It t Ta Xr ober_set_header 3 Ta 2: Vt int , unsigned int
155.It x Ta Fn ober_add_nstring Ta 2: Vt char * , size_t
156.It \&( Ta Fn ober_add_set Ta 0
157.It \&) Ta see below Ta 0
158.It \&. Ta Fn ober_add_eoc Ta 0
159.It 0 Ta Fn ober_add_null Ta 0
160.It { Ta Fn ober_add_sequence Ta 0
161.It } Ta see below Ta 0
162.El
163.Pp
164The
165.Sq e
166and
167.Sq t
168bytes are special in so far as they do not create new elements.
169The
170.Sq e
171byte adds an element that was already created earlier into or behind
172the previous element, or into and behind
173.Fa ber
174if the
175.Sq e
176is the first byte in
177.Fa fmt ,
178just like the
179.Fn ober_add_*
180functions would add a new element.
181The
182.Sq t
183byte changes the class and type of the last element, or of
184.Fa ber
185if
186.Sq t
187is the first byte in
188.Fa fmt ,
189without changing its position relative to other elements.
190.Pp
191A closing brace or parenthesis closes an open sequence or set,
192if any, such that the next element will be added behind rather
193than into the sequence or set.
194Only one sequence or set can be open at any time.
195Nesting is not supported without multiple function calls.
196.Sh RETURN VALUES
197Upon successful completion,
198these functions return a pointer to a populated
199.Vt ber_element .
200Otherwise
201.Dv NULL
202is returned and the global variable
203.Va errno
204is set to indicate the error.
205.Pp
206.Fn ober_printf_elements
207returns
208.Dv NULL
209without setting
210.Va errno
211if
212.Fa fmt
213is an empty string and
214.Fa ber
215is
216.Dv NULL .
217.Sh SEE ALSO
218.Xr ober_get_string 3 ,
219.Xr ober_oid_cmp 3 ,
220.Xr ober_read_elements 3 ,
221.Xr ober_set_header 3
222.Sh STANDARDS
223ITU-T Recommendation X.690, also known as ISO/IEC 8825-1:
224Information technology - ASN.1 encoding rules.
225.Sh HISTORY
226These functions first appeared as internal functions in
227.Xr snmpd 8
228in
229.Ox 4.2
230and were moved to libutil in
231.Ox 6.6 .
232.Sh AUTHORS
233.An -nosplit
234The BER library was written by
235.An Claudio Jeker Aq Mt claudio@openbsd.org ,
236.An Marc Balmer Aq Mt marc@openbsd.org
237and
238.An Reyk Floeter Aq Mt reyk@openbsd.org .