.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "BER 3pm" .TH BER 3pm "2020-11-29" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" BER \- Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1) .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 4 \& use BER; \& $encoded = encode_sequence (encode_int (123), encode_string ("foo")); \& ($i, $s) = decode_by_template ($encoded, "%{%i%s"); \& # $i will now be 123, $s the string "foo". .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is a simple library to encode and decode data using the Basic Encoding Rules (\s-1BER\s0) of Abstract Syntax Notation One (\s-1ASN.1\s0). It does not claim to be a complete implementation of the standard, but implements enough of the \s-1BER\s0 standard to encode and decode \s-1SNMP\s0 messages. .SH "VARIABLES" .IX Header "VARIABLES" .ie n .SS "$pretty_print_timeticks (default: 1)" .el .SS "\f(CW$pretty_print_timeticks\fP (default: 1)" .IX Subsection "$pretty_print_timeticks (default: 1)" If non-zero (the default), \f(CW\*(C`pretty_print\*(C'\fR will convert TimeTicks to \&\*(L"human readable\*(R" strings containing days, hours, minutes and seconds. .PP If the variable is zero, \f(CW\*(C`pretty_print\*(C'\fR will simply return an unsigned integer representing hundredths of seconds. If you prefer this, bind \f(CW$pretty_print_timeticks\fR to zero. .ie n .SS "$errmsg \- error message from last failed operation." .el .SS "\f(CW$errmsg\fP \- error message from last failed operation." .IX Subsection "$errmsg - error message from last failed operation." When they encounter errors, the routines in this module will generally return \f(CW\*(C`undef\*(C'\fR) and leave an informative error message in \&\f(CW$errmsg\fR). .SH "METHODS" .IX Header "METHODS" .SS "\fBencode_int_0()\fP \- encode the integer 0." .IX Subsection "encode_int_0() - encode the integer 0." This is functionally identical to \f(CWencode_int(0)\fR. .ie n .SS "\fBencode_int()\fP \- encode an integer using the generic ""integer"" type tag." .el .SS "\fBencode_int()\fP \- encode an integer using the generic ``integer'' type tag." .IX Subsection "encode_int() - encode an integer using the generic integer type tag." .SS "\fBencode_uinteger32()\fP \- encode an integer using the \s-1SNMP\s0 UInteger32 tag." .IX Subsection "encode_uinteger32() - encode an integer using the SNMP UInteger32 tag." .SS "\fBencode_counter32()\fP \- encode an integer using the \s-1SNMP\s0 Counter32 tag." .IX Subsection "encode_counter32() - encode an integer using the SNMP Counter32 tag." .SS "\fBencode_counter64()\fP \- encode an integer using the \s-1SNMP\s0 Counter64 tag." .IX Subsection "encode_counter64() - encode an integer using the SNMP Counter64 tag." .SS "\fBencode_gauge32()\fP \- encode an integer using the \s-1SNMP\s0 Gauge32 tag." .IX Subsection "encode_gauge32() - encode an integer using the SNMP Gauge32 tag." .SS "\fBencode_oid()\fP \- encode an object \s-1ID,\s0 passed as a list of sub-IDs." .IX Subsection "encode_oid() - encode an object ID, passed as a list of sub-IDs." .Vb 1 \& $encoded = encode_oid (1,3,6,1,...); .Ve .SS "\fBencode_null()\fP \- encode a null object." .IX Subsection "encode_null() - encode a null object." This is used e.g. in binding lists for variables that don't have a value (yet) .SS "\fBencode_sequence()\fP" .IX Subsection "encode_sequence()" .SS "\fBencode_tagged_sequence()\fP" .IX Subsection "encode_tagged_sequence()" .Vb 2 \& $encoded = encode_sequence (encoded1, encoded2, ...); \& $encoded = encode_tagged_sequence (tag, encoded1, encoded2, ...); .Ve .PP Take already encoded values, and extend them to an encoded sequence. \&\f(CW\*(C`encoded_sequence\*(C'\fR uses the generic sequence tag, while with \&\f(CW\*(C`encode_tagged_sequence\*(C'\fR you can specify your own tag. .SS "\fBencode_string()\fP \- encode a Perl string as an \s-1OCTET STRING.\s0" .IX Subsection "encode_string() - encode a Perl string as an OCTET STRING." .SS "\fBencode_ip_address()\fP \- encode an IPv4 address." .IX Subsection "encode_ip_address() - encode an IPv4 address." This can either be passed as a four-octet sequence in \fBnetwork byte order\fR, or as a text string in dotted-quad notation, e.g. \*(L"192.0.2.234\*(R". .ie n .SS "\fBencode_timeticks()\fP \- encode an integer as a ""TimeTicks"" object." .el .SS "\fBencode_timeticks()\fP \- encode an integer as a \f(CWTimeTicks\fP object." .IX Subsection "encode_timeticks() - encode an integer as a TimeTicks object." The integer should count hundredths of a second since the epoch defined by \f(CW\*(C`sysUpTime.0\*(C'\fR. .SS "\fBpretty_print()\fP \- convert an encoded byte sequence into human-readable form." .IX Subsection "pretty_print() - convert an encoded byte sequence into human-readable form." This function can be extended by registering pretty-printing methods for specific type codes. Most \s-1BER\s0 type codes used in \s-1SNMP\s0 already have such methods pre-registered by default. See \&\f(CW\*(C`register_pretty_printer\*(C'\fR for how new methods can be added. .SS "\fBhex_string()\fP \- convert \s-1OCTET STRING\s0 to hexadecimal notation." .IX Subsection "hex_string() - convert OCTET STRING to hexadecimal notation." .SS "\fBhex_string_of_type()\fP \- convert octet string to hex, and check type against given tag." .IX Subsection "hex_string_of_type() - convert octet string to hex, and check type against given tag." .SS "\fBdecode_by_template()\fP \- decode complex object according to a template." .IX Subsection "decode_by_template() - decode complex object according to a template." .Vb 1 \& ($var1, ...) = decode_by_template ($pdu, $template, ...); .Ve .PP The template can contain various \f(CW%X\fR directives. Some directives consume additional arguments following the template itself. Most directives will cause values to be returned. The values are returned as a sequence in the order of the directives that generated them. .IP "%{ \- decode sequence." 4 .IX Item "%{ - decode sequence." This doesn't assign any return value, just checks and skips the tag/length fields of the sequence. By default, the tag should be the generic sequence tag, but a tag can also be specified in the directive. The directive can either specify the tag as a prefix, e.g. \f(CW\*(C`%99{\*(C'\fR will require a sequence tag of 99, or if the directive is given as \f(CW\*(C`%*{\*(C'\fR, the tag will be taken from the next argument. .ie n .IP "%s \- decode string" 4 .el .IP "\f(CW%s\fR \- decode string" 4 .IX Item "%s - decode string" .PD 0 .ie n .IP "%i \- decode integer" 4 .el .IP "\f(CW%i\fR \- decode integer" 4 .IX Item "%i - decode integer" .ie n .IP "%u \- decode unsigned integer" 4 .el .IP "\f(CW%u\fR \- decode unsigned integer" 4 .IX Item "%u - decode unsigned integer" .ie n .IP "%O \- decode Object \s-1ID\s0 (\s-1OID\s0)" 4 .el .IP "\f(CW%O\fR \- decode Object \s-1ID\s0 (\s-1OID\s0)" 4 .IX Item "%O - decode Object ID (OID)" .ie n .IP "%A \- decode IPv4 address" 4 .el .IP "\f(CW%A\fR \- decode IPv4 address" 4 .IX Item "%A - decode IPv4 address" .IP "%@ \- assigns the remaining undecoded part of the \s-1PDU\s0 to the next return value." 4 .IX Item "%@ - assigns the remaining undecoded part of the PDU to the next return value." .PD .SS "\fBdecode_sequence()\fP \- Split sequence into components." .IX Subsection "decode_sequence() - Split sequence into components." .Vb 1 \& ($first, $rest) = decode_sequence ($pdu); .Ve .PP Checks whether the \s-1PDU\s0 has a sequence type tag and a plausible length field. Splits the initial element off the list, and returns both this and the remainder of the \s-1PDU.\s0 .SS "\fBregister_pretty_printer()\fP \- register pretty-printing methods for typecodes." .IX Subsection "register_pretty_printer() - register pretty-printing methods for typecodes." This function takes a hashref that specifies functions to call when the specified value type is being printed. It returns the number of functions that were registered. .SH "AUTHORS" .IX Header "AUTHORS" Created by: Simon Leinen .PP Contributions and fixes by: .IP "Andrzej Tobola : Added long String decode" 4 .IX Item "Andrzej Tobola : Added long String decode" .PD 0 .IP "Tobias Oetiker : Added 5 Byte Integer decode ..." 4 .IX Item "Tobias Oetiker : Added 5 Byte Integer decode ..." .ie n .IP "Dave Rand : Added ""SysUpTime"" decode" 4 .el .IP "Dave Rand : Added \f(CWSysUpTime\fR decode" 4 .IX Item "Dave Rand : Added SysUpTime decode" .IP "Philippe Simonet : Support larger subids" 4 .IX Item "Philippe Simonet : Support larger subids" .IP "Yufang \s-1HU\s0 : Support even larger subids" 4 .IX Item "Yufang HU : Support even larger subids" .ie n .IP "Mike Mitchell : New generalized ""encode_int()""" 4 .el .IP "Mike Mitchell : New generalized \f(CWencode_int()\fR" 4 .IX Item "Mike Mitchell : New generalized encode_int()" .ie n .IP "Mike Diehn : ""encode_ip_address()""" 4 .el .IP "Mike Diehn : \f(CWencode_ip_address()\fR" 4 .IX Item "Mike Diehn : encode_ip_address()" .ie n .IP "Rik Hoorelbeke : ""encode_oid()"" fix" 4 .el .IP "Rik Hoorelbeke : \f(CWencode_oid()\fR fix" 4 .IX Item "Rik Hoorelbeke : encode_oid() fix" .ie n .IP "Brett T Warden : pretty ""UInteger32""" 4 .el .IP "Brett T Warden : pretty \f(CWUInteger32\fR" 4 .IX Item "Brett T Warden : pretty UInteger32" .IP "Bert Driehuis : Handle SNMPv2 exception codes" 4 .IX Item "Bert Driehuis : Handle SNMPv2 exception codes" .IP "Jakob Ilves (/IlvJa) : \s-1PDU\s0 decoding" 4 .IX Item "Jakob Ilves (/IlvJa) : PDU decoding" .IP "Jan Kasprzak : Fix for \s-1PDU\s0 syntax check" 4 .IX Item "Jan Kasprzak : Fix for PDU syntax check" .IP "Milen Pavlov : Recognize variant length for ints" 4 .IX Item "Milen Pavlov : Recognize variant length for ints" .PD .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright (c) 1995\-2009, Simon Leinen. .PP This program is free software; you can redistribute it under the \&\*(L"Artistic License 2.0\*(R" included in this distribution (file \*(L"Artistic\*(R").