1.\"
| 1.\"
|
| 2.\" Copyright (c) 2004-2005
3.\" Hartmut Brandt.
4.\" All rights reserved.
|
2.\" Copyright (c) 2001-2003
3.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
4.\" All rights reserved.
5.\"
6.\" Author: Harti Brandt <harti@freebsd.org>
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\" notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\" notice, this list of conditions and the following disclaimer in the
15.\" documentation and/or other materials provided with the distribution.
16.\"
17.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
21.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
22.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
23.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
24.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
25.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
26.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
27.\" SUCH DAMAGE.
28.\"
| 5.\" Copyright (c) 2001-2003
6.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
7.\" All rights reserved.
8.\"
9.\" Author: Harti Brandt <harti@freebsd.org>
10.\"
11.\" Redistribution and use in source and binary forms, with or without
12.\" modification, are permitted provided that the following conditions
13.\" are met:
14.\" 1. Redistributions of source code must retain the above copyright
15.\" notice, this list of conditions and the following disclaimer.
16.\" 2. Redistributions in binary form must reproduce the above copyright
17.\" notice, this list of conditions and the following disclaimer in the
18.\" documentation and/or other materials provided with the distribution.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
|
29.\" $Begemot: bsnmp/lib/asn1.3,v 1.6 2005/02/25 11:55:57 brandt_h Exp $
| 32.\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $
|
30.\"
| 33.\"
|
31.Dd August 15, 2002
| 34.Dd October 4, 2005
|
32.Dt ASN1 3
33.Os
34.Sh NAME
35.Nm asn_get_header ,
36.Nm asn_put_header ,
37.Nm asn_put_temp_header ,
38.Nm asn_commit_header ,
39.Nm asn_get_integer_raw ,
40.Nm asn_get_integer ,
41.Nm asn_put_integer ,
42.Nm asn_get_octetstring_raw ,
43.Nm asn_get_octetstring ,
44.Nm asn_put_octetstring ,
45.Nm asn_get_null_raw ,
46.Nm asn_get_null ,
47.Nm asn_put_null ,
48.Nm asn_put_exception ,
49.Nm asn_get_objid_raw ,
50.Nm asn_get_objid ,
51.Nm asn_put_objid ,
52.Nm asn_get_sequence ,
53.Nm asn_get_ipaddress_raw ,
54.Nm asn_get_ipaddress ,
55.Nm asn_put_ipaddress ,
56.Nm asn_get_uint32_raw ,
57.Nm asn_put_uint32 ,
58.Nm asn_get_counter64_raw ,
59.Nm asn_put_counter64 ,
60.Nm asn_get_timeticks ,
61.Nm asn_put_timeticks ,
62.Nm asn_skip ,
63.Nm asn_slice_oid ,
64.Nm asn_append_oid ,
65.Nm asn_compare_oid ,
66.Nm asn_is_suboid ,
67.Nm asn_oid2str_r ,
68.Nm asn_oid2str
69.Nd "ASN.1 library for SNMP"
70.Sh LIBRARY
71Begemot SNMP library
72.Pq libbsnmp, -lbsnmp
73.Sh SYNOPSIS
74.In bsnmp/asn1.h
75.Ft enum asn_err
76.Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp"
77.Ft enum asn_err
78.Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len"
79.Ft enum asn_err
80.Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr"
81.Ft enum asn_err
82.Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr"
83.Ft enum asn_err
84.Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res"
85.Ft enum asn_err
86.Fn asn_get_integer "struct asn_buf *buf" "int32_t *res"
87.Ft enum asn_err
88.Fn asn_put_integer "struct asn_buf *buf" "int32_t arg"
89.Ft enum asn_err
90.Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize"
91.Ft enum asn_err
92.Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize"
93.Ft enum asn_err
94.Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize"
95.Ft enum asn_err
96.Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len"
97.Ft enum asn_err
98.Fn asn_get_null "struct asn_buf *buf"
99.Ft enum asn_err
100.Fn asn_put_null "struct asn_buf *buf"
101.Ft enum asn_err
102.Fn asn_put_exception "struct asn_buf *buf" "u_int type"
103.Ft enum asn_err
104.Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid"
105.Ft enum asn_err
106.Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid"
107.Ft enum asn_err
108.Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid"
109.Ft enum asn_err
110.Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp"
111.Ft enum asn_err
112.Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa"
113.Ft enum asn_err
114.Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa"
115.Ft enum asn_err
116.Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa"
117.Ft enum asn_err
118.Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res"
119.Ft enum asn_err
120.Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val"
121.Ft enum asn_err
122.Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res"
123.Ft enum asn_err
124.Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val"
125.Ft enum asn_err
126.Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp"
127.Ft enum asn_err
128.Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val"
129.Ft enum asn_err
130.Fn asn_skip "struct asn_buf *buf" "asn_len_t len"
131.Ft void
132.Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to"
133.Ft void
134.Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from"
135.Ft int
136.Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
137.Ft int
138.Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
139.Ft char *
140.Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf"
141.Ft char *
142.Fn asn_oid2str "const struct asn_oid *oid"
143.Sh DESCRIPTION
144The ASN.1 library contains routines to handle ASN.1 encoding for SNMP.
| 35.Dt ASN1 3
36.Os
37.Sh NAME
38.Nm asn_get_header ,
39.Nm asn_put_header ,
40.Nm asn_put_temp_header ,
41.Nm asn_commit_header ,
42.Nm asn_get_integer_raw ,
43.Nm asn_get_integer ,
44.Nm asn_put_integer ,
45.Nm asn_get_octetstring_raw ,
46.Nm asn_get_octetstring ,
47.Nm asn_put_octetstring ,
48.Nm asn_get_null_raw ,
49.Nm asn_get_null ,
50.Nm asn_put_null ,
51.Nm asn_put_exception ,
52.Nm asn_get_objid_raw ,
53.Nm asn_get_objid ,
54.Nm asn_put_objid ,
55.Nm asn_get_sequence ,
56.Nm asn_get_ipaddress_raw ,
57.Nm asn_get_ipaddress ,
58.Nm asn_put_ipaddress ,
59.Nm asn_get_uint32_raw ,
60.Nm asn_put_uint32 ,
61.Nm asn_get_counter64_raw ,
62.Nm asn_put_counter64 ,
63.Nm asn_get_timeticks ,
64.Nm asn_put_timeticks ,
65.Nm asn_skip ,
66.Nm asn_slice_oid ,
67.Nm asn_append_oid ,
68.Nm asn_compare_oid ,
69.Nm asn_is_suboid ,
70.Nm asn_oid2str_r ,
71.Nm asn_oid2str
72.Nd "ASN.1 library for SNMP"
73.Sh LIBRARY
74Begemot SNMP library
75.Pq libbsnmp, -lbsnmp
76.Sh SYNOPSIS
77.In bsnmp/asn1.h
78.Ft enum asn_err
79.Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp"
80.Ft enum asn_err
81.Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len"
82.Ft enum asn_err
83.Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr"
84.Ft enum asn_err
85.Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr"
86.Ft enum asn_err
87.Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res"
88.Ft enum asn_err
89.Fn asn_get_integer "struct asn_buf *buf" "int32_t *res"
90.Ft enum asn_err
91.Fn asn_put_integer "struct asn_buf *buf" "int32_t arg"
92.Ft enum asn_err
93.Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize"
94.Ft enum asn_err
95.Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize"
96.Ft enum asn_err
97.Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize"
98.Ft enum asn_err
99.Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len"
100.Ft enum asn_err
101.Fn asn_get_null "struct asn_buf *buf"
102.Ft enum asn_err
103.Fn asn_put_null "struct asn_buf *buf"
104.Ft enum asn_err
105.Fn asn_put_exception "struct asn_buf *buf" "u_int type"
106.Ft enum asn_err
107.Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid"
108.Ft enum asn_err
109.Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid"
110.Ft enum asn_err
111.Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid"
112.Ft enum asn_err
113.Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp"
114.Ft enum asn_err
115.Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa"
116.Ft enum asn_err
117.Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa"
118.Ft enum asn_err
119.Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa"
120.Ft enum asn_err
121.Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res"
122.Ft enum asn_err
123.Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val"
124.Ft enum asn_err
125.Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res"
126.Ft enum asn_err
127.Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val"
128.Ft enum asn_err
129.Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp"
130.Ft enum asn_err
131.Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val"
132.Ft enum asn_err
133.Fn asn_skip "struct asn_buf *buf" "asn_len_t len"
134.Ft void
135.Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to"
136.Ft void
137.Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from"
138.Ft int
139.Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
140.Ft int
141.Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
142.Ft char *
143.Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf"
144.Ft char *
145.Fn asn_oid2str "const struct asn_oid *oid"
146.Sh DESCRIPTION
147The ASN.1 library contains routines to handle ASN.1 encoding for SNMP.
|
145It supports only the restricted form of ASN.1 as required by SNMP. There
146are two basic structures used throughout the library:
| 148It supports only the restricted form of ASN.1 as required by SNMP.
149There are two basic structures used throughout the library:
|
147.Bd -literal -offset indent
148/* these restrictions are in the SMI */
149#define ASN_MAXID 0xffffffff
150#define ASN_MAXOIDLEN 128
151
152/* type of subidentifiers */
153typedef u_int32_t asn_subid_t;
154
155struct asn_oid {
156 u_int len;
157 asn_subid_t subs[ASN_MAXOIDLEN];
158};
159.Ed
160.Pp
161This structure represents an OID with the restrictions defined in the SNMP
162SMI.
163.Fa len
164holds the current length of the OID and
165.Fa subs
166holds the elements of the OID.
167.Bd -literal -offset indent
168struct asn_buf {
169 union {
170 u_char *ptr;
171 const u_char *cptr;
172 } asn_u;
173 size_t asn_len;
174};
175#define asn_cptr asn_u.cptr
176#define asn_ptr asn_u.ptr
177.Ed
178.Pp
| 150.Bd -literal -offset indent
151/* these restrictions are in the SMI */
152#define ASN_MAXID 0xffffffff
153#define ASN_MAXOIDLEN 128
154
155/* type of subidentifiers */
156typedef u_int32_t asn_subid_t;
157
158struct asn_oid {
159 u_int len;
160 asn_subid_t subs[ASN_MAXOIDLEN];
161};
162.Ed
163.Pp
164This structure represents an OID with the restrictions defined in the SNMP
165SMI.
166.Fa len
167holds the current length of the OID and
168.Fa subs
169holds the elements of the OID.
170.Bd -literal -offset indent
171struct asn_buf {
172 union {
173 u_char *ptr;
174 const u_char *cptr;
175 } asn_u;
176 size_t asn_len;
177};
178#define asn_cptr asn_u.cptr
179#define asn_ptr asn_u.ptr
180.Ed
181.Pp
|
179This structure is used to encode and decode ASN.1. It describes the output
| 182This structure is used to encode and decode ASN.1.
183It describes the output
|
180buffer for encoding routines and the input buffer for decoding routines.
181For encoding
182.Fa asn_len
| 184buffer for encoding routines and the input buffer for decoding routines.
185For encoding
186.Fa asn_len
|
183holds the number of remaining free octets in the buffer. The first free byte
184is pointed to by
| 187holds the number of remaining free octets in the buffer.
188The first free byte is pointed to by
|
185.Fa asn_ptr .
186For decoding
187.Fa asn_len
| 189.Fa asn_ptr .
190For decoding
191.Fa asn_len
|
188holds the number of remaining bytes to decode. The next byte to decode is pointed
189to by
| 192holds the number of remaining bytes to decode.
193The next byte to decode is pointed to by
|
190.Fa asn_cptr .
191.Pp
192Most of the functions return an error code
193.Fa "enum asn_error" :
194.Bd -literal -offset indent
195enum asn_err {
196 /* conversion was ok */
197 ASN_ERR_OK = 0,
198 /* conversion failed and stopped */
199 ASN_ERR_FAILED = 1 | 0x1000,
200 /* length field bad, value skipped */
201 ASN_ERR_BADLEN = 2,
202 /* out of buffer, stopped */
203 ASN_ERR_EOBUF = 3 | 0x1000,
204 /* length ok, but value is out of range */
205 ASN_ERR_RANGE = 4,
206 /* not the expected tag, stopped */
207 ASN_ERR_TAG = 5 | 0x1000,
208};
209#define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0)
210.Ed
211.Pp
212If
213.Fn ASN_ERR_STOPPED
214returns true, the error was fatal and processing has stopped at the point
215of error.
216.Pp
217The function
218.Fn asn_get_header
| 194.Fa asn_cptr .
195.Pp
196Most of the functions return an error code
197.Fa "enum asn_error" :
198.Bd -literal -offset indent
199enum asn_err {
200 /* conversion was ok */
201 ASN_ERR_OK = 0,
202 /* conversion failed and stopped */
203 ASN_ERR_FAILED = 1 | 0x1000,
204 /* length field bad, value skipped */
205 ASN_ERR_BADLEN = 2,
206 /* out of buffer, stopped */
207 ASN_ERR_EOBUF = 3 | 0x1000,
208 /* length ok, but value is out of range */
209 ASN_ERR_RANGE = 4,
210 /* not the expected tag, stopped */
211 ASN_ERR_TAG = 5 | 0x1000,
212};
213#define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0)
214.Ed
215.Pp
216If
217.Fn ASN_ERR_STOPPED
218returns true, the error was fatal and processing has stopped at the point
219of error.
220.Pp
221The function
222.Fn asn_get_header
|
219reads the next header from the input octet stream. It returns the tag
220in the variable pointed to by
| 223reads the next header from the input octet stream.
224It returns the tag in the variable pointed to by
|
221.Fa type
222(note that only single byte tags are supported) and the decoded length field
223in the value pointed to by
224.Fa lenp
| 225.Fa type
226(note that only single byte tags are supported) and the decoded length field
227in the value pointed to by
228.Fa lenp
|
225(this is restricted to a unsigned 32-bit value). All errors in this function
226are fatal and stop processing.
| 229(this is restricted to a unsigned 32-bit value).
230All errors in this function are fatal and stop processing.
|
227.Pp
228The function
229.Fn asn_put_header
230writes an ASN.1 header.
231.Fa type
| 231.Pp
232The function
233.Fn asn_put_header
234writes an ASN.1 header.
235.Fa type
|
232is the tag to write and is restricted to one byte tags (i.e. tags
| 236is the tag to write and is restricted to one byte tags (i.e., tags
|
233lesser or equal than 0x30).
234.Fa len
235is the length of the value and is restricted to 16-bit.
236.Pp
237The functions
238.Fn asn_put_temp_header
239and
240.Fn asn_commit_header
241are used to write a header when the length of the value is not known in
242advance, for example, for sequences.
243.Fn asn_put_temp_header
244writes a header with the given tag
245.Fa type
246and space for the maximum supported length field and sets the pointer pointed
247to by
248.Fa ptr
| 237lesser or equal than 0x30).
238.Fa len
239is the length of the value and is restricted to 16-bit.
240.Pp
241The functions
242.Fn asn_put_temp_header
243and
244.Fn asn_commit_header
245are used to write a header when the length of the value is not known in
246advance, for example, for sequences.
247.Fn asn_put_temp_header
248writes a header with the given tag
249.Fa type
250and space for the maximum supported length field and sets the pointer pointed
251to by
252.Fa ptr
|
249to the begin of this length field. This pointer must then be fed into
| 253to the begin of this length field.
254This pointer must then be fed into
|
250.Fn asn_commit_header
| 255.Fn asn_commit_header
|
251directly after writing the value to the buffer. The function will compute the
| 256directly after writing the value to the buffer.
257The function will compute the
|
252length, insert it into the right place and shift the value if the resulting
253length field is shorter than the estimated one.
254.Pp
255The function
256.Fn asn_get_integer_raw
| 258length, insert it into the right place and shift the value if the resulting
259length field is shorter than the estimated one.
260.Pp
261The function
262.Fn asn_get_integer_raw
|
257is used to decode a signed integer value (32-bit). It assumes, that the
| 263is used to decode a signed integer value (32-bit).
264It assumes, that the
|
258header of the integer has been decoded already.
259.Fa len
260is the length obtained from the ASN.1 header and the integer will be returned
261in the value pointed to by
262.Fa res .
263.Pp
264The function
265.Fn asn_get_integer
| 265header of the integer has been decoded already.
266.Fa len
267is the length obtained from the ASN.1 header and the integer will be returned
268in the value pointed to by
269.Fa res .
270.Pp
271The function
272.Fn asn_get_integer
|
266decodes a complete 32-bit signed integer including the header. If the
267tag is wrong
| 273decodes a complete 32-bit signed integer including the header.
274If the tag is wrong
|
268.Li ASN_ERR_TAG
269is returned.
270The function
271.Fn asn_put_integer
272encodes a 32-bit signed integer.
273.Pp
274The function
275.Fn asn_get_octetstring_raw
| 275.Li ASN_ERR_TAG
276is returned.
277The function
278.Fn asn_put_integer
279encodes a 32-bit signed integer.
280.Pp
281The function
282.Fn asn_get_octetstring_raw
|
276decodes the value field of an ASN.1 octet string. The length obtained from the
277header must be fed into the
| 283decodes the value field of an ASN.1 octet string.
284The length obtained from the header must be fed into the
|
278.Fa len
279argument and
280.Fa out
| 285.Fa len
286argument and
287.Fa out
|
281must point to a buffer to receive the octet string. On entry to the function
| 288must point to a buffer to receive the octet string.
289On entry to the function
|
282.Fa outsize
| 290.Fa outsize
|
283must point to the size of the buffer. On exit
| 291must point to the size of the buffer.
292On exit
|
284.Fa outsize
285will point to the number of octets decoded (if no error occurs this will be
286equal to
287.Fa len ).
288The function
289.Fn asn_get_octetstring
290decodes an octetstring including the header.
291.Fa out
292must point to a buffer to receive the string,
293.Fa outsize
| 293.Fa outsize
294will point to the number of octets decoded (if no error occurs this will be
295equal to
296.Fa len ).
297The function
298.Fn asn_get_octetstring
299decodes an octetstring including the header.
300.Fa out
301must point to a buffer to receive the string,
302.Fa outsize
|
294must point to the size of the buffer. On exit of the function
| 303must point to the size of the buffer.
304On exit of the function
|
295.Fa outsize
296will point to the number of octets decoded.
297The function
298.Fn asn_put_octetstring
299encodes an octetstring (including the header).
300.Fa str
301points to the string to encode and
302.Fa strsize
303is the length of the string (the string may contain embedded
304.Li NUL Ns s).
305.Pp
306The function
307.Fn asn_get_null_raw
308decodes a null value.
309.Fa len
310is the length obtained from the header and must be 0.
311The function
312.Fn asn_get_null
313decodes a null including the header and the function
314.Fn asn_put_null
315encodes a null.
316.Pp
317The function
318.Fn asn_put_exception
| 305.Fa outsize
306will point to the number of octets decoded.
307The function
308.Fn asn_put_octetstring
309encodes an octetstring (including the header).
310.Fa str
311points to the string to encode and
312.Fa strsize
313is the length of the string (the string may contain embedded
314.Li NUL Ns s).
315.Pp
316The function
317.Fn asn_get_null_raw
318decodes a null value.
319.Fa len
320is the length obtained from the header and must be 0.
321The function
322.Fn asn_get_null
323decodes a null including the header and the function
324.Fn asn_put_null
325encodes a null.
326.Pp
327The function
328.Fn asn_put_exception
|
319is used to encode an SNMPv2 exception. The exception type is
| 329is used to encode an SNMPv2 exception.
330The exception type is
|
320.Fa type .
321.Pp
322The function
323.Fn asn_get_objid_raw
324is used to decode an OID value.
325.Fa len
326must be the value length obtained from the header and
327.Fa oid
328will receive the decoded OID.
329The function
330.Fn asn_get_objid
331decodes a complete OID (including the header) and the function
332.Fn asn_put_objid
333encodes a complete OID.
334.Pp
335The function
336.Fn asn_get_sequence
337decodes a sequence header.
338The length of the sequence value will be stored in the value pointed to by
339.Fa lenp .
340.Pp
341The function
342.Fn asn_get_ipaddress_raw
343decodes an IP address value.
344.Fa len
345is the length from the header and must be 4.
346.Fa ipa
347will receive the decoded IP address and must point to a buffer of at least
348four bytes.
349The function
350.Fn asn_get_ipaddress
351decodes a complete IP address (including the header) and
352.Fn asn_put_ipaddress
353encodes an IP address.
354.Pp
355The function
356.Fn asn_get_uint32_raw
357decodes an unsigned 32-bit integer value.
358.Fa len
359is the length from the header and
360.Fa res
361will get the decoded value.
362The function
363.Fn asn_put_uint32
364encodes an unsigned 32-bit integer value and inserts the tag given in
365.Fa type
366into the header.
367.Pp
368The function
369.Fn asn_get_counter64_raw
370decodes an unsigned 64-bit integer value.
371.Fa len
| 331.Fa type .
332.Pp
333The function
334.Fn asn_get_objid_raw
335is used to decode an OID value.
336.Fa len
337must be the value length obtained from the header and
338.Fa oid
339will receive the decoded OID.
340The function
341.Fn asn_get_objid
342decodes a complete OID (including the header) and the function
343.Fn asn_put_objid
344encodes a complete OID.
345.Pp
346The function
347.Fn asn_get_sequence
348decodes a sequence header.
349The length of the sequence value will be stored in the value pointed to by
350.Fa lenp .
351.Pp
352The function
353.Fn asn_get_ipaddress_raw
354decodes an IP address value.
355.Fa len
356is the length from the header and must be 4.
357.Fa ipa
358will receive the decoded IP address and must point to a buffer of at least
359four bytes.
360The function
361.Fn asn_get_ipaddress
362decodes a complete IP address (including the header) and
363.Fn asn_put_ipaddress
364encodes an IP address.
365.Pp
366The function
367.Fn asn_get_uint32_raw
368decodes an unsigned 32-bit integer value.
369.Fa len
370is the length from the header and
371.Fa res
372will get the decoded value.
373The function
374.Fn asn_put_uint32
375encodes an unsigned 32-bit integer value and inserts the tag given in
376.Fa type
377into the header.
378.Pp
379The function
380.Fn asn_get_counter64_raw
381decodes an unsigned 64-bit integer value.
382.Fa len
|
372must be the value length from the header. The resulting value is
373stored into the variable pointed to by
| 383must be the value length from the header.
384The resulting value is stored into the variable pointed to by
|
374.Fa res .
375The function
376.Fn asn_put_counter64
377encodes a complete unsigned 64-bit value.
378.Pp
379The function
380.Fn asn_get_timeticks
381decodes an ASN.1 object of type
382.Li TIMETICKS
383and the function
384.Fn asn_put_timeticks
385encodes such an object.
386.Pp
387The function
388.Fn asn_skip
389can be used to skip
390.Fa len
391bytes in the input buffer.
392.Pp
393The function
394.Fn asn_slice_oid
| 385.Fa res .
386The function
387.Fn asn_put_counter64
388encodes a complete unsigned 64-bit value.
389.Pp
390The function
391.Fn asn_get_timeticks
392decodes an ASN.1 object of type
393.Li TIMETICKS
394and the function
395.Fn asn_put_timeticks
396encodes such an object.
397.Pp
398The function
399.Fn asn_skip
400can be used to skip
401.Fa len
402bytes in the input buffer.
403.Pp
404The function
405.Fn asn_slice_oid
|
395splits a part out from an OID. It takes all the subids from the OID
396pointed to by
| 406splits a part out from an OID.
407It takes all the subids from the OID pointed to by
|
397.Fa src
398starting with the subid at position
399.Fa from
| 408.Fa src
409starting with the subid at position
410.Fa from
|
400(the first subid beeing subid 0) up to, but not including, subid
| 411(the first subid being subid 0) up to, but not including, subid
|
401.Fa to
402and generates a new OID in
403.Fa dest .
404If
405.Fa to
406is less or equal to
407.Fa from
408the resulting OID will have a length of zero.
409.Pp
410The function
411.Fn asn_append_oid
412appends the OID
413.Fa from
414to the OID
415.Fa to
| 412.Fa to
413and generates a new OID in
414.Fa dest .
415If
416.Fa to
417is less or equal to
418.Fa from
419the resulting OID will have a length of zero.
420.Pp
421The function
422.Fn asn_append_oid
423appends the OID
424.Fa from
425to the OID
426.Fa to
|
416given that the resulting OID is not too long. If the maximum length is exceeded
417the result is undefined.
| 427given that the resulting OID is not too long.
428If the maximum length is exceeded the result is undefined.
|
418.Pp
419The function
420.Fn asn_compare_oid
421compares two oids and returns the values
422.Li -1 ,
423.Li 0 or
424.Li +1
425when
426.Fa oid1
427is lesser than, equal, or larger than
428.Fa oid2
429resp.
430.Pp
431The function
432.Fn asn_is_suboid
433returns 1 if
434.Fa oid1
435is equal to the leading part of
436.Fa oid2 .
437It returns 0 otherwise.
438.Pp
439The function
440.Fn asn_oid2str_r
441makes a printable string from
442.Fa oid .
443The buffer pointed to by
444.Fa str
| 429.Pp
430The function
431.Fn asn_compare_oid
432compares two oids and returns the values
433.Li -1 ,
434.Li 0 or
435.Li +1
436when
437.Fa oid1
438is lesser than, equal, or larger than
439.Fa oid2
440resp.
441.Pp
442The function
443.Fn asn_is_suboid
444returns 1 if
445.Fa oid1
446is equal to the leading part of
447.Fa oid2 .
448It returns 0 otherwise.
449.Pp
450The function
451.Fn asn_oid2str_r
452makes a printable string from
453.Fa oid .
454The buffer pointed to by
455.Fa str
|
445must be large enough to hold the result. The constant
| 456must be large enough to hold the result.
457The constant
|
446.Li ASN_OIDSTRLEN
447is defined to be the length of the maximum string generated by this function
448(including the trailing NUL).
449The function
450.Fn asn_oid2str
451makes a printable string from
452.Fa oid
453into a private buffer that is overwritten by each call.
454.Sh DIAGNOSTICS
| 458.Li ASN_OIDSTRLEN
459is defined to be the length of the maximum string generated by this function
460(including the trailing NUL).
461The function
462.Fn asn_oid2str
463makes a printable string from
464.Fa oid
465into a private buffer that is overwritten by each call.
466.Sh DIAGNOSTICS
|
455When an error occures in any of the function the function pointed to
| 467When an error occurs in any of the function the function pointed to
|
456by the global pointer
457.Bd -literal -offset indent
458extern void (*asn_error)(const struct asn_buf *, const char *, ...);
459.Ed
460.Pp
461is called with the current buffer (this may be
462.Li NULL )
463and a
464.Xr printf 3
465style format string.
466There is a default error handler in the library that prints a message
467starting with
468.Sq ASN.1:
469followed by the error message and an optional dump of the buffer.
470.Sh SEE ALSO
471.Xr gensnmptree 1 ,
| 468by the global pointer
469.Bd -literal -offset indent
470extern void (*asn_error)(const struct asn_buf *, const char *, ...);
471.Ed
472.Pp
473is called with the current buffer (this may be
474.Li NULL )
475and a
476.Xr printf 3
477style format string.
478There is a default error handler in the library that prints a message
479starting with
480.Sq ASN.1:
481followed by the error message and an optional dump of the buffer.
482.Sh SEE ALSO
483.Xr gensnmptree 1 ,
|
472.Xr snmpd 1 ,
| 484.Xr bsnmpd 1 ,
|
473.Xr bsnmpagent 3 ,
474.Xr bsnmpclient 3 ,
475.Xr bsnmplib 3
476.Sh STANDARDS
477This implementation conforms to the applicable IETF RFCs and ITU-T
478recommendations.
479.Sh AUTHORS
480.An Hartmut Brandt Aq harti@freebsd.org
| 485.Xr bsnmpagent 3 ,
486.Xr bsnmpclient 3 ,
487.Xr bsnmplib 3
488.Sh STANDARDS
489This implementation conforms to the applicable IETF RFCs and ITU-T
490recommendations.
491.Sh AUTHORS
492.An Hartmut Brandt Aq harti@freebsd.org
|