1.\" |
2.\" Copyright (c) 2004-2005 3.\" Hartmut Brandt. 4.\" All rights reserved. |
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 --- 11 unchanged lines hidden (view full) --- 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.\" |
32.\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $ |
33.\" |
34.Dd October 4, 2005 |
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 , --- 97 unchanged lines hidden (view full) --- 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. |
148It supports only the restricted form of ASN.1 as required by SNMP. 149There are two basic structures used throughout the library: |
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 --- 16 unchanged lines hidden (view full) --- 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 |
182This structure is used to encode and decode ASN.1. 183It describes the output |
184buffer for encoding routines and the input buffer for decoding routines. 185For encoding 186.Fa asn_len |
187holds the number of remaining free octets in the buffer. 188The first free byte is pointed to by |
189.Fa asn_ptr . 190For decoding 191.Fa asn_len |
192holds the number of remaining bytes to decode. 193The next byte to decode is pointed to by |
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, --- 13 unchanged lines hidden (view full) --- 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 |
223reads the next header from the input octet stream. 224It returns the tag in the variable pointed to by |
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 |
229(this is restricted to a unsigned 32-bit value). 230All errors in this function are fatal and stop processing. |
231.Pp 232The function 233.Fn asn_put_header 234writes an ASN.1 header. 235.Fa type |
236is the tag to write and is restricted to one byte tags (i.e., tags |
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 |
253to the begin of this length field. 254This pointer must then be fed into |
255.Fn asn_commit_header |
256directly after writing the value to the buffer. 257The function will compute the |
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 |
263is used to decode a signed integer value (32-bit). 264It assumes, that the |
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 |
273decodes a complete 32-bit signed integer including the header. 274If the tag is wrong |
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 |
283decodes the value field of an ASN.1 octet string. 284The length obtained from the header must be fed into the |
285.Fa len 286argument and 287.Fa out |
288must point to a buffer to receive the octet string. 289On entry to the function |
290.Fa outsize |
291must point to the size of the buffer. 292On exit |
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 |
303must point to the size of the buffer. 304On exit of the function |
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 --- 8 unchanged lines hidden (view full) --- 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 |
329is used to encode an SNMPv2 exception. 330The exception type is |
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 --- 36 unchanged lines hidden (view full) --- 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 |
383must be the value length from the header. 384The resulting value is stored into the variable pointed to by |
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 --- 5 unchanged lines hidden (view full) --- 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 |
406splits a part out from an OID. 407It takes all the subids from the OID pointed to by |
408.Fa src 409starting with the subid at position 410.Fa from |
411(the first subid being subid 0) up to, but not including, subid |
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 |
427given that the resulting OID is not too long. 428If the maximum length is exceeded the result is undefined. |
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 --- 11 unchanged lines hidden (view full) --- 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 |
456must be large enough to hold the result. 457The constant |
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 |
467When an error occurs in any of the function the function pointed to |
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 , |
484.Xr bsnmpd 1 , |
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 |