summaryrefslogtreecommitdiff
path: root/contrib/bsnmp/lib/asn1.3
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/bsnmp/lib/asn1.3')
-rw-r--r--contrib/bsnmp/lib/asn1.3484
1 files changed, 484 insertions, 0 deletions
diff --git a/contrib/bsnmp/lib/asn1.3 b/contrib/bsnmp/lib/asn1.3
new file mode 100644
index 0000000000000..3751e50cdb1cf
--- /dev/null
+++ b/contrib/bsnmp/lib/asn1.3
@@ -0,0 +1,484 @@
+.\"
+.\" Copyright (c) 2001-2003
+.\" Fraunhofer Institute for Open Communication Systems (FhG Fokus).
+.\" All rights reserved.
+.\"
+.\" Author: Harti Brandt <harti@freebsd.org>
+.\"
+.\" Redistribution of this software and documentation 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 or documentation 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.
+.\" 3. Neither the name of the Institute nor the names of its contributors
+.\" may be used to endorse or promote products derived from this software
+.\" without specific prior written permission.
+.\"
+.\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY FRAUNHOFER FOKUS
+.\" AND ITS 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
+.\" FRAUNHOFER FOKUS OR ITS 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.2 2002/08/16 10:02:53 hbb Exp $
+.\"
+.Dd August 15, 2002
+.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 beeing 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 occures 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 snmpd 1 ,
+.Xr gensnmptree 1 ,
+.Xr bsnmplib 3
+.Xr bsnmpclient 3 ,
+.Xr bsnmpagent 3
+.Sh STANDARDS
+This implementation conforms to the applicable IETF RFCs and ITU-T
+recommendations.
+.Sh AUTHORS
+.An Hartmut Brandt Aq brandt@fokus.gmd.de