1.\"
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
--- 11 unchanged lines hidden (view full) ---
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.\"
29.\" $Begemot: bsnmp/lib/asn1.3,v 1.6 2005/02/25 11:55:57 brandt_h Exp $
30.\"
31.Dd August 15, 2002
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 ,
--- 97 unchanged lines hidden (view full) ---
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.
145It supports only the restricted form of ASN.1 as required by SNMP. There
146are 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
--- 16 unchanged lines hidden (view full) ---
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
179This structure is used to encode and decode ASN.1. It describes the output
180buffer for encoding routines and the input buffer for decoding routines.
181For encoding
182.Fa asn_len
183holds the number of remaining free octets in the buffer. The first free byte
184is pointed to by
185.Fa asn_ptr .
186For decoding
187.Fa asn_len
188holds the number of remaining bytes to decode. The next byte to decode is pointed
189to 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,
--- 13 unchanged lines hidden (view full) ---
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
219reads the next header from the input octet stream. It returns the tag
220in 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(this is restricted to a unsigned 32-bit value). All errors in this function
226are fatal and stop processing.
227.Pp
228The function
229.Fn asn_put_header
230writes an ASN.1 header.
231.Fa type
232is 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
249to the begin of this length field. This pointer must then be fed into
250.Fn asn_commit_header
251directly after writing the value to the buffer. The 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
257is used to decode a signed integer value (32-bit). It 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
266decodes a complete 32-bit signed integer including the header. If the
267tag 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
276decodes the value field of an ASN.1 octet string. The length obtained from the
277header must be fed into the
278.Fa len
279argument and
280.Fa out
281must point to a buffer to receive the octet string. On entry to the function
282.Fa outsize
283must point to the size of the buffer. On 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
294must point to the size of the buffer. On 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
--- 8 unchanged lines hidden (view full) ---
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
319is used to encode an SNMPv2 exception. The 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
--- 36 unchanged lines hidden (view full) ---
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
372must be the value length from the header. The resulting value is
373stored 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
--- 5 unchanged lines hidden (view full) ---
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
395splits a part out from an OID. It takes all the subids from the OID
396pointed to by
397.Fa src
398starting with the subid at position
399.Fa from
400(the first subid beeing 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
416given that the resulting OID is not too long. If the maximum length is exceeded
417the 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
--- 11 unchanged lines hidden (view full) ---
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
445must be large enough to hold the result. The 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
455When an error occures 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 ,
472.Xr snmpd 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
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
--- 11 unchanged lines hidden (view full) ---
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.\"
29.\" $Begemot: bsnmp/lib/asn1.3,v 1.6 2005/02/25 11:55:57 brandt_h Exp $
30.\"
31.Dd August 15, 2002
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 ,
--- 97 unchanged lines hidden (view full) ---
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.
145It supports only the restricted form of ASN.1 as required by SNMP. There
146are 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
--- 16 unchanged lines hidden (view full) ---
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
179This structure is used to encode and decode ASN.1. It describes the output
180buffer for encoding routines and the input buffer for decoding routines.
181For encoding
182.Fa asn_len
183holds the number of remaining free octets in the buffer. The first free byte
184is pointed to by
185.Fa asn_ptr .
186For decoding
187.Fa asn_len
188holds the number of remaining bytes to decode. The next byte to decode is pointed
189to 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,
--- 13 unchanged lines hidden (view full) ---
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
219reads the next header from the input octet stream. It returns the tag
220in 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(this is restricted to a unsigned 32-bit value). All errors in this function
226are fatal and stop processing.
227.Pp
228The function
229.Fn asn_put_header
230writes an ASN.1 header.
231.Fa type
232is 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
249to the begin of this length field. This pointer must then be fed into
250.Fn asn_commit_header
251directly after writing the value to the buffer. The 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
257is used to decode a signed integer value (32-bit). It 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
266decodes a complete 32-bit signed integer including the header. If the
267tag 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
276decodes the value field of an ASN.1 octet string. The length obtained from the
277header must be fed into the
278.Fa len
279argument and
280.Fa out
281must point to a buffer to receive the octet string. On entry to the function
282.Fa outsize
283must point to the size of the buffer. On 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
294must point to the size of the buffer. On 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
--- 8 unchanged lines hidden (view full) ---
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
319is used to encode an SNMPv2 exception. The 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
--- 36 unchanged lines hidden (view full) ---
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
372must be the value length from the header. The resulting value is
373stored 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
--- 5 unchanged lines hidden (view full) ---
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
395splits a part out from an OID. It takes all the subids from the OID
396pointed to by
397.Fa src
398starting with the subid at position
399.Fa from
400(the first subid beeing 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
416given that the resulting OID is not too long. If the maximum length is exceeded
417the 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
--- 11 unchanged lines hidden (view full) ---
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
445must be large enough to hold the result. The 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
455When an error occures 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 ,
472.Xr snmpd 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