/contrib/bsnmp/lib/asn1.3
https://bitbucket.org/freebsd/freebsd-head/ · Unknown · 492 lines · 490 code · 2 blank · 0 comment · 0 complexity · f1c02913bd43e21f7e4d2f9be552addf MD5 · raw file
- .\"
- .\" Copyright (c) 2004-2005
- .\" Hartmut Brandt.
- .\" All rights reserved.
- .\" Copyright (c) 2001-2003
- .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
- .\" All rights reserved.
- .\"
- .\" Author: Harti Brandt <harti@FreeBSD.org>
- .\"
- .\" Redistribution and use in source and binary forms, with or without
- .\" modification, are permitted provided that the following conditions
- .\" are met:
- .\" 1. Redistributions of source code must retain the above copyright
- .\" notice, this list of conditions and the following disclaimer.
- .\" 2. Redistributions in binary form must reproduce the above copyright
- .\" notice, this list of conditions and the following disclaimer in the
- .\" documentation and/or other materials provided with the distribution.
- .\"
- .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND
- .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
- .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
- .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE
- .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
- .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
- .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
- .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
- .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
- .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
- .\" SUCH DAMAGE.
- .\"
- .\" $Begemot: bsnmp/lib/asn1.3,v 1.9 2005/10/04 08:46:49 brandt_h Exp $
- .\"
- .Dd October 4, 2005
- .Dt ASN1 3
- .Os
- .Sh NAME
- .Nm asn_get_header ,
- .Nm asn_put_header ,
- .Nm asn_put_temp_header ,
- .Nm asn_commit_header ,
- .Nm asn_get_integer_raw ,
- .Nm asn_get_integer ,
- .Nm asn_put_integer ,
- .Nm asn_get_octetstring_raw ,
- .Nm asn_get_octetstring ,
- .Nm asn_put_octetstring ,
- .Nm asn_get_null_raw ,
- .Nm asn_get_null ,
- .Nm asn_put_null ,
- .Nm asn_put_exception ,
- .Nm asn_get_objid_raw ,
- .Nm asn_get_objid ,
- .Nm asn_put_objid ,
- .Nm asn_get_sequence ,
- .Nm asn_get_ipaddress_raw ,
- .Nm asn_get_ipaddress ,
- .Nm asn_put_ipaddress ,
- .Nm asn_get_uint32_raw ,
- .Nm asn_put_uint32 ,
- .Nm asn_get_counter64_raw ,
- .Nm asn_put_counter64 ,
- .Nm asn_get_timeticks ,
- .Nm asn_put_timeticks ,
- .Nm asn_skip ,
- .Nm asn_slice_oid ,
- .Nm asn_append_oid ,
- .Nm asn_compare_oid ,
- .Nm asn_is_suboid ,
- .Nm asn_oid2str_r ,
- .Nm asn_oid2str
- .Nd "ASN.1 library for SNMP"
- .Sh LIBRARY
- Begemot SNMP library
- .Pq libbsnmp, -lbsnmp
- .Sh SYNOPSIS
- .In bsnmp/asn1.h
- .Ft enum asn_err
- .Fn asn_get_header "struct asn_buf *buf" "u_char *type" "asn_len_t *lenp"
- .Ft enum asn_err
- .Fn asn_put_header "struct asn_buf *buf" "u_char type" "asn_len_t len"
- .Ft enum asn_err
- .Fn asn_put_temp_header "struct asn_buf *buf" "u_char type" "u_char **ptr"
- .Ft enum asn_err
- .Fn asn_commit_header "struct asn_buf *buf" "u_char *ptr"
- .Ft enum asn_err
- .Fn asn_get_integer_raw "struct asn_buf *buf" "asn_len_t len" "int32_t *res"
- .Ft enum asn_err
- .Fn asn_get_integer "struct asn_buf *buf" "int32_t *res"
- .Ft enum asn_err
- .Fn asn_put_integer "struct asn_buf *buf" "int32_t arg"
- .Ft enum asn_err
- .Fn asn_get_octetstring_raw "struct asn_buf *buf" "asn_len_t len" "u_char *out" "u_int *outsize"
- .Ft enum asn_err
- .Fn asn_get_octetstring "struct asn_buf *buf" "u_char *out" "u_int *outsize"
- .Ft enum asn_err
- .Fn asn_put_octetstring "struct asn_buf *buf" "const u_char *str" "u_int strsize"
- .Ft enum asn_err
- .Fn asn_get_null_raw "struct asn_buf *buf" "asn_len_t len"
- .Ft enum asn_err
- .Fn asn_get_null "struct asn_buf *buf"
- .Ft enum asn_err
- .Fn asn_put_null "struct asn_buf *buf"
- .Ft enum asn_err
- .Fn asn_put_exception "struct asn_buf *buf" "u_int type"
- .Ft enum asn_err
- .Fn asn_get_objid_raw "struct asn_buf *buf" "asn_len_t len" "struct asn_oid *oid"
- .Ft enum asn_err
- .Fn asn_get_objid "struct asn_buf *buf" "struct asn_oid *oid"
- .Ft enum asn_err
- .Fn asn_put_objid "struct asn_buf *buf" "const struct asn_oid *oid"
- .Ft enum asn_err
- .Fn asn_get_sequence "struct asn_buf *buf" "asn_len_t *lenp"
- .Ft enum asn_err
- .Fn asn_get_ipaddress_raw "struct asn_buf *buf" "asn_len_t len" "u_char *ipa"
- .Ft enum asn_err
- .Fn asn_get_ipaddress "struct asn_buf *buf" "u_char *ipa"
- .Ft enum asn_err
- .Fn asn_put_ipaddress "struct asn_buf *buf" "const u_char *ipa"
- .Ft enum asn_err
- .Fn asn_get_uint32_raw "struct asn_buf *buf" "asn_len_t len" "u_int32_t *res"
- .Ft enum asn_err
- .Fn asn_put_uint32 "struct asn_buf *buf" "u_char type" "u_int32_t val"
- .Ft enum asn_err
- .Fn asn_get_counter64_raw "struct asn_buf *buf" "asn_len_t len" "u_int64_t *res"
- .Ft enum asn_err
- .Fn asn_put_counter64 "struct asn_buf *buf" "u_int64_t val"
- .Ft enum asn_err
- .Fn asn_get_timeticks "struct asn_buf *buf" "u_int32_t *valp"
- .Ft enum asn_err
- .Fn asn_put_timeticks "struct asn_buf *buf" "u_int32_t val"
- .Ft enum asn_err
- .Fn asn_skip "struct asn_buf *buf" "asn_len_t len"
- .Ft void
- .Fn asn_slice_oid "struct asn_oid *dest" "const struct asn_oid *src" "u_int from" "u_int to"
- .Ft void
- .Fn asn_append_oid "struct asn_oid *to" "const struct asn_oid *from"
- .Ft int
- .Fn asn_compare_oid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
- .Ft int
- .Fn asn_is_suboid "const struct asn_oid *oid1" "const struct asn_oid *oid2"
- .Ft char *
- .Fn asn_oid2str_r "const struct asn_oid *oid" "char *buf"
- .Ft char *
- .Fn asn_oid2str "const struct asn_oid *oid"
- .Sh DESCRIPTION
- The ASN.1 library contains routines to handle ASN.1 encoding for SNMP.
- It supports only the restricted form of ASN.1 as required by SNMP.
- There are two basic structures used throughout the library:
- .Bd -literal -offset indent
- /* these restrictions are in the SMI */
- #define ASN_MAXID 0xffffffff
- #define ASN_MAXOIDLEN 128
- /* type of subidentifiers */
- typedef u_int32_t asn_subid_t;
- struct asn_oid {
- u_int len;
- asn_subid_t subs[ASN_MAXOIDLEN];
- };
- .Ed
- .Pp
- This structure represents an OID with the restrictions defined in the SNMP
- SMI.
- .Fa len
- holds the current length of the OID and
- .Fa subs
- holds the elements of the OID.
- .Bd -literal -offset indent
- struct asn_buf {
- union {
- u_char *ptr;
- const u_char *cptr;
- } asn_u;
- size_t asn_len;
- };
- #define asn_cptr asn_u.cptr
- #define asn_ptr asn_u.ptr
- .Ed
- .Pp
- This structure is used to encode and decode ASN.1.
- It describes the output
- buffer for encoding routines and the input buffer for decoding routines.
- For encoding
- .Fa asn_len
- holds the number of remaining free octets in the buffer.
- The first free byte is pointed to by
- .Fa asn_ptr .
- For decoding
- .Fa asn_len
- holds the number of remaining bytes to decode.
- The next byte to decode is pointed to by
- .Fa asn_cptr .
- .Pp
- Most of the functions return an error code
- .Fa "enum asn_error" :
- .Bd -literal -offset indent
- enum asn_err {
- /* conversion was ok */
- ASN_ERR_OK = 0,
- /* conversion failed and stopped */
- ASN_ERR_FAILED = 1 | 0x1000,
- /* length field bad, value skipped */
- ASN_ERR_BADLEN = 2,
- /* out of buffer, stopped */
- ASN_ERR_EOBUF = 3 | 0x1000,
- /* length ok, but value is out of range */
- ASN_ERR_RANGE = 4,
- /* not the expected tag, stopped */
- ASN_ERR_TAG = 5 | 0x1000,
- };
- #define ASN_ERR_STOPPED(E) (((E) & 0x1000) != 0)
- .Ed
- .Pp
- If
- .Fn ASN_ERR_STOPPED
- returns true, the error was fatal and processing has stopped at the point
- of error.
- .Pp
- The function
- .Fn asn_get_header
- reads the next header from the input octet stream.
- It returns the tag in the variable pointed to by
- .Fa type
- (note that only single byte tags are supported) and the decoded length field
- in the value pointed to by
- .Fa lenp
- (this is restricted to a unsigned 32-bit value).
- All errors in this function are fatal and stop processing.
- .Pp
- The function
- .Fn asn_put_header
- writes an ASN.1 header.
- .Fa type
- is the tag to write and is restricted to one byte tags (i.e., tags
- lesser or equal than 0x30).
- .Fa len
- is the length of the value and is restricted to 16-bit.
- .Pp
- The functions
- .Fn asn_put_temp_header
- and
- .Fn asn_commit_header
- are used to write a header when the length of the value is not known in
- advance, for example, for sequences.
- .Fn asn_put_temp_header
- writes a header with the given tag
- .Fa type
- and space for the maximum supported length field and sets the pointer pointed
- to by
- .Fa ptr
- to the begin of this length field.
- This pointer must then be fed into
- .Fn asn_commit_header
- directly after writing the value to the buffer.
- The function will compute the
- length, insert it into the right place and shift the value if the resulting
- length field is shorter than the estimated one.
- .Pp
- The function
- .Fn asn_get_integer_raw
- is used to decode a signed integer value (32-bit).
- It assumes, that the
- header of the integer has been decoded already.
- .Fa len
- is the length obtained from the ASN.1 header and the integer will be returned
- in the value pointed to by
- .Fa res .
- .Pp
- The function
- .Fn asn_get_integer
- decodes a complete 32-bit signed integer including the header.
- If the tag is wrong
- .Li ASN_ERR_TAG
- is returned.
- The function
- .Fn asn_put_integer
- encodes a 32-bit signed integer.
- .Pp
- The function
- .Fn asn_get_octetstring_raw
- decodes the value field of an ASN.1 octet string.
- The length obtained from the header must be fed into the
- .Fa len
- argument and
- .Fa out
- must point to a buffer to receive the octet string.
- On entry to the function
- .Fa outsize
- must point to the size of the buffer.
- On exit
- .Fa outsize
- will point to the number of octets decoded (if no error occurs this will be
- equal to
- .Fa len ).
- The function
- .Fn asn_get_octetstring
- decodes an octetstring including the header.
- .Fa out
- must point to a buffer to receive the string,
- .Fa outsize
- must point to the size of the buffer.
- On exit of the function
- .Fa outsize
- will point to the number of octets decoded.
- The function
- .Fn asn_put_octetstring
- encodes an octetstring (including the header).
- .Fa str
- points to the string to encode and
- .Fa strsize
- is the length of the string (the string may contain embedded
- .Li NUL Ns s).
- .Pp
- The function
- .Fn asn_get_null_raw
- decodes a null value.
- .Fa len
- is the length obtained from the header and must be 0.
- The function
- .Fn asn_get_null
- decodes a null including the header and the function
- .Fn asn_put_null
- encodes a null.
- .Pp
- The function
- .Fn asn_put_exception
- is used to encode an SNMPv2 exception.
- The exception type is
- .Fa type .
- .Pp
- The function
- .Fn asn_get_objid_raw
- is used to decode an OID value.
- .Fa len
- must be the value length obtained from the header and
- .Fa oid
- will receive the decoded OID.
- The function
- .Fn asn_get_objid
- decodes a complete OID (including the header) and the function
- .Fn asn_put_objid
- encodes a complete OID.
- .Pp
- The function
- .Fn asn_get_sequence
- decodes a sequence header.
- The length of the sequence value will be stored in the value pointed to by
- .Fa lenp .
- .Pp
- The function
- .Fn asn_get_ipaddress_raw
- decodes an IP address value.
- .Fa len
- is the length from the header and must be 4.
- .Fa ipa
- will receive the decoded IP address and must point to a buffer of at least
- four bytes.
- The function
- .Fn asn_get_ipaddress
- decodes a complete IP address (including the header) and
- .Fn asn_put_ipaddress
- encodes an IP address.
- .Pp
- The function
- .Fn asn_get_uint32_raw
- decodes an unsigned 32-bit integer value.
- .Fa len
- is the length from the header and
- .Fa res
- will get the decoded value.
- The function
- .Fn asn_put_uint32
- encodes an unsigned 32-bit integer value and inserts the tag given in
- .Fa type
- into the header.
- .Pp
- The function
- .Fn asn_get_counter64_raw
- decodes an unsigned 64-bit integer value.
- .Fa len
- must be the value length from the header.
- The resulting value is stored into the variable pointed to by
- .Fa res .
- The function
- .Fn asn_put_counter64
- encodes a complete unsigned 64-bit value.
- .Pp
- The function
- .Fn asn_get_timeticks
- decodes an ASN.1 object of type
- .Li TIMETICKS
- and the function
- .Fn asn_put_timeticks
- encodes such an object.
- .Pp
- The function
- .Fn asn_skip
- can be used to skip
- .Fa len
- bytes in the input buffer.
- .Pp
- The function
- .Fn asn_slice_oid
- splits a part out from an OID.
- It takes all the subids from the OID pointed to by
- .Fa src
- starting with the subid at position
- .Fa from
- (the first subid being subid 0) up to, but not including, subid
- .Fa to
- and generates a new OID in
- .Fa dest .
- If
- .Fa to
- is less or equal to
- .Fa from
- the resulting OID will have a length of zero.
- .Pp
- The function
- .Fn asn_append_oid
- appends the OID
- .Fa from
- to the OID
- .Fa to
- given that the resulting OID is not too long.
- If the maximum length is exceeded the result is undefined.
- .Pp
- The function
- .Fn asn_compare_oid
- compares two oids and returns the values
- .Li -1 ,
- .Li 0 or
- .Li +1
- when
- .Fa oid1
- is lesser than, equal, or larger than
- .Fa oid2
- resp.
- .Pp
- The function
- .Fn asn_is_suboid
- returns 1 if
- .Fa oid1
- is equal to the leading part of
- .Fa oid2 .
- It returns 0 otherwise.
- .Pp
- The function
- .Fn asn_oid2str_r
- makes a printable string from
- .Fa oid .
- The buffer pointed to by
- .Fa str
- must be large enough to hold the result.
- The constant
- .Li ASN_OIDSTRLEN
- is defined to be the length of the maximum string generated by this function
- (including the trailing NUL).
- The function
- .Fn asn_oid2str
- makes a printable string from
- .Fa oid
- into a private buffer that is overwritten by each call.
- .Sh DIAGNOSTICS
- When an error occurs in any of the function the function pointed to
- by the global pointer
- .Bd -literal -offset indent
- extern void (*asn_error)(const struct asn_buf *, const char *, ...);
- .Ed
- .Pp
- is called with the current buffer (this may be
- .Li NULL )
- and a
- .Xr printf 3
- style format string.
- There is a default error handler in the library that prints a message
- starting with
- .Sq ASN.1:
- followed by the error message and an optional dump of the buffer.
- .Sh SEE ALSO
- .Xr gensnmptree 1 ,
- .Xr bsnmpd 1 ,
- .Xr bsnmpagent 3 ,
- .Xr bsnmpclient 3 ,
- .Xr bsnmplib 3
- .Sh STANDARDS
- This implementation conforms to the applicable IETF RFCs and ITU-T
- recommendations.
- .Sh AUTHORS
- .An Hartmut Brandt Aq harti@FreeBSD.org