contrib/bsnmp/lib/asn1.3

   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
  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 .\"
  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 ,
  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
  74 Begemot 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
 147 The ASN.1 library contains routines to handle ASN.1 encoding for SNMP.
 148 It supports only the restricted form of ASN.1 as required by SNMP.
 149 There 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 */
 156 typedef u_int32_t asn_subid_t;
 157
 158 struct asn_oid {
 159         u_int   len;
 160         asn_subid_t subs[ASN_MAXOIDLEN];
 161 };
 162 .Ed
 163 .Pp
 164 This structure represents an OID with the restrictions defined in the SNMP
 165 SMI.
 166 .Fa len
 167 holds the current length of the OID and
 168 .Fa subs
 169 holds the elements of the OID.
 170 .Bd -literal -offset indent
 171 struct 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
 182 This structure is used to encode and decode ASN.1.
 183 It describes the output
 184 buffer for encoding routines and the input buffer for decoding routines.
 185 For encoding
 186 .Fa asn_len
 187 holds the number of remaining free octets in the buffer.
 188 The first free byte is pointed to by
 189 .Fa asn_ptr .
 190 For decoding
 191 .Fa asn_len
 192 holds the number of remaining bytes to decode.
 193 The next byte to decode is pointed to by
 194 .Fa asn_cptr .
 195 .Pp
 196 Most of the functions return an error code
 197 .Fa "enum asn_error" :
 198 .Bd -literal -offset indent
 199 enum 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
 216 If
 217 .Fn ASN_ERR_STOPPED
 218 returns true, the error was fatal and processing has stopped at the point
 219 of error.
 220 .Pp
 221 The function
 222 .Fn asn_get_header
 223 reads the next header from the input octet stream.
 224 It 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
 227 in the value pointed to by
 228 .Fa lenp
 229 (this is restricted to a unsigned 32-bit value).
 230 All errors in this function are fatal and stop processing.
 231 .Pp
 232 The function
 233 .Fn asn_put_header
 234 writes an ASN.1 header.
 235 .Fa type
 236 is the tag to write and is restricted to one byte tags (i.e., tags
 237 lesser or equal than 0x30).
 238 .Fa len
 239 is the length of the value and is restricted to 16-bit.
 240 .Pp
 241 The functions
 242 .Fn asn_put_temp_header
 243 and
 244 .Fn asn_commit_header
 245 are used to write a header when the length of the value is not known in
 246 advance, for example, for sequences.
 247 .Fn asn_put_temp_header
 248 writes a header with the given tag
 249 .Fa type
 250 and space for the maximum supported length field and sets the pointer pointed
 251 to by
 252 .Fa ptr
 253 to the begin of this length field.
 254 This pointer must then be fed into
 255 .Fn asn_commit_header
 256 directly after writing the value to the buffer.
 257 The function will compute the
 258 length, insert it into the right place and shift the value if the resulting
 259 length field is shorter than the estimated one.
 260 .Pp
 261 The function
 262 .Fn asn_get_integer_raw
 263 is used to decode a signed integer value (32-bit).
 264 It assumes, that the
 265 header of the integer has been decoded already.
 266 .Fa len
 267 is the length obtained from the ASN.1 header and the integer will be returned
 268 in the value pointed to by
 269 .Fa res .
 270 .Pp
 271 The function
 272 .Fn asn_get_integer
 273 decodes a complete 32-bit signed integer including the header.
 274 If the tag is wrong
 275 .Li ASN_ERR_TAG
 276 is returned.
 277 The function
 278 .Fn asn_put_integer
 279 encodes a 32-bit signed integer.
 280 .Pp
 281 The function
 282 .Fn asn_get_octetstring_raw
 283 decodes the value field of an ASN.1 octet string.
 284 The length obtained from the header must be fed into the
 285 .Fa len
 286 argument and
 287 .Fa out
 288 must point to a buffer to receive the octet string.
 289 On entry to the function
 290 .Fa outsize
 291 must point to the size of the buffer.
 292 On exit
 293 .Fa outsize
 294 will point to the number of octets decoded (if no error occurs this will be
 295 equal to
 296 .Fa len ).
 297 The function
 298 .Fn asn_get_octetstring
 299 decodes an octetstring including the header.
 300 .Fa out
 301 must point to a buffer to receive the string,
 302 .Fa outsize
 303 must point to the size of the buffer.
 304 On exit of the function
 305 .Fa outsize
 306 will point to the number of octets decoded.
 307 The function
 308 .Fn asn_put_octetstring
 309 encodes an octetstring (including the header).
 310 .Fa str
 311 points to the string to encode and
 312 .Fa strsize
 313 is the length of the string (the string may contain embedded
 314 .Li NUL Ns s).
 315 .Pp
 316 The function
 317 .Fn asn_get_null_raw
 318 decodes a null value.
 319 .Fa len
 320 is the length obtained from the header and must be 0.
 321 The function
 322 .Fn asn_get_null
 323 decodes a null including the header and the function
 324 .Fn asn_put_null
 325 encodes a null.
 326 .Pp
 327 The function
 328 .Fn asn_put_exception
 329 is used to encode an SNMPv2 exception.
 330 The exception type is
 331 .Fa type .
 332 .Pp
 333 The function
 334 .Fn asn_get_objid_raw
 335 is used to decode an OID value.
 336 .Fa len
 337 must be the value length obtained from the header and
 338 .Fa oid
 339 will receive the decoded OID.
 340 The function
 341 .Fn asn_get_objid
 342 decodes a complete OID (including the header) and the function
 343 .Fn asn_put_objid
 344 encodes a complete OID.
 345 .Pp
 346 The function
 347 .Fn asn_get_sequence
 348 decodes a sequence header.
 349 The length of the sequence value will be stored in the value pointed to by
 350 .Fa lenp .
 351 .Pp
 352 The function
 353 .Fn asn_get_ipaddress_raw
 354 decodes an IP address value.
 355 .Fa len
 356 is the length from the header and must be 4.
 357 .Fa ipa
 358 will receive the decoded IP address and must point to a buffer of at least
 359 four bytes.
 360 The function
 361 .Fn asn_get_ipaddress
 362 decodes a complete IP address (including the header) and
 363 .Fn asn_put_ipaddress
 364 encodes an IP address.
 365 .Pp
 366 The function
 367 .Fn asn_get_uint32_raw
 368 decodes an unsigned 32-bit integer value.
 369 .Fa len
 370 is the length from the header and
 371 .Fa res
 372 will get the decoded value.
 373 The function
 374 .Fn asn_put_uint32
 375 encodes an unsigned 32-bit integer value and inserts the tag given in
 376 .Fa type
 377 into the header.
 378 .Pp
 379 The function
 380 .Fn asn_get_counter64_raw
 381 decodes an unsigned 64-bit integer value.
 382 .Fa len
 383 must be the value length from the header.
 384 The resulting value is stored into the variable pointed to by
 385 .Fa res .
 386 The function
 387 .Fn asn_put_counter64
 388 encodes a complete unsigned 64-bit value.
 389 .Pp
 390 The function
 391 .Fn asn_get_timeticks
 392 decodes an ASN.1 object of type
 393 .Li TIMETICKS
 394 and the function
 395 .Fn asn_put_timeticks
 396 encodes such an object.
 397 .Pp
 398 The function
 399 .Fn asn_skip
 400 can be used to skip
 401 .Fa len
 402 bytes in the input buffer.
 403 .Pp
 404 The function
 405 .Fn asn_slice_oid
 406 splits a part out from an OID.
 407 It takes all the subids from the OID pointed to by
 408 .Fa src
 409 starting with the subid at position
 410 .Fa from
 411 (the first subid being subid 0) up to, but not including, subid
 412 .Fa to
 413 and generates a new OID in
 414 .Fa dest .
 415 If
 416 .Fa to
 417 is less or equal to
 418 .Fa from
 419 the resulting OID will have a length of zero.
 420 .Pp
 421 The function
 422 .Fn asn_append_oid
 423 appends the OID
 424 .Fa from
 425 to the OID
 426 .Fa to
 427 given that the resulting OID is not too long.
 428 If the maximum length is exceeded the result is undefined.
 429 .Pp
 430 The function
 431 .Fn asn_compare_oid
 432 compares two oids and returns the values
 433 .Li -1 ,
 434 .Li 0 or
 435 .Li +1
 436 when
 437 .Fa oid1
 438 is lesser than, equal, or larger than
 439 .Fa oid2
 440 resp.
 441 .Pp
 442 The function
 443 .Fn asn_is_suboid
 444 returns 1 if
 445 .Fa oid1
 446 is equal to the leading part of
 447 .Fa oid2 .
 448 It returns 0 otherwise.
 449 .Pp
 450 The function
 451 .Fn asn_oid2str_r
 452 makes a printable string from
 453 .Fa oid .
 454 The buffer pointed to by
 455 .Fa str
 456 must be large enough to hold the result.
 457 The constant
 458 .Li ASN_OIDSTRLEN
 459 is defined to be the length of the maximum string generated by this function
 460 (including the trailing NUL).
 461 The function
 462 .Fn asn_oid2str
 463 makes a printable string from
 464 .Fa oid
 465 into a private buffer that is overwritten by each call.
 466 .Sh DIAGNOSTICS
 467 When an error occurs in any of the function the function pointed to
 468 by the global pointer
 469 .Bd -literal -offset indent
 470 extern void (*asn_error)(const struct asn_buf *, const char *, ...);
 471 .Ed
 472 .Pp
 473 is called with the current buffer (this may be
 474 .Li NULL )
 475 and a
 476 .Xr printf 3
 477 style format string.
 478 There is a default error handler in the library that prints a message
 479 starting with
 480 .Sq ASN.1:
 481 followed 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
 489 This implementation conforms to the applicable IETF RFCs and ITU-T
 490 recommendations.
 491 .Sh AUTHORS
 492 .An Hartmut Brandt Aq harti@FreeBSD.org