--- name: "BER" section: "3pm" platform: "linux" package: "libsnmp-session-perl" version: "1.16-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/BER" --- # BER(3pm) Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1) ## NAME BER - Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1) ## SYNOPSIS ``` 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". ``` ## DESCRIPTION This is a simple library to encode and decode data using the Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1). It does not claim to be a complete implementation of the standard, but implements enough of the BER standard to encode and decode SNMP messages. ## VARIABLES ### $pretty\_print\_timeticks (default: 1) If non-zero (the default), `"pretty_print"` will convert TimeTicks to "human readable" strings containing days, hours, minutes and seconds. If the variable is zero, `"pretty_print"` will simply return an unsigned integer representing hundredths of seconds. If you prefer this, bind `$pretty_print_timeticks` to zero. ### $errmsg - error message from last failed operation. When they encounter errors, the routines in this module will generally return `"undef"`) and leave an informative error message in `$errmsg`). ## METHODS ### encode\_int\_0() - encode the integer 0. This is functionally identical to `encode_int(0)`. ### encode\_int() - encode an integer using the generic "integer" type tag. ### encode\_uinteger32() - encode an integer using the SNMP UInteger32 tag. ### encode\_counter32() - encode an integer using the SNMP Counter32 tag. ### encode\_counter64() - encode an integer using the SNMP Counter64 tag. ### encode\_gauge32() - encode an integer using the SNMP Gauge32 tag. ### encode\_oid() - encode an object ID, passed as a list of sub-IDs. ``` $encoded = encode_oid (1,3,6,1,...); ``` ### encode\_null() - encode a null object. This is used e.g. in binding lists for variables that don't have a value (yet) ### encode\_sequence() ### encode\_tagged\_sequence() ``` $encoded = encode_sequence (encoded1, encoded2, ...); $encoded = encode_tagged_sequence (tag, encoded1, encoded2, ...); ``` Take already encoded values, and extend them to an encoded sequence. `"encoded_sequence"` uses the generic sequence tag, while with `"encode_tagged_sequence"` you can specify your own tag. ### encode\_string() - encode a Perl string as an OCTET STRING. ### encode\_ip\_address() - encode an IPv4 address. This can either be passed as a four-octet sequence in **network byte** **order**, or as a text string in dotted-quad notation, e.g. "192.0.2.234". ### encode\_timeticks() - encode an integer as a "TimeTicks" object. The integer should count hundredths of a second since the epoch defined by `"sysUpTime.0"`. ### 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 BER type codes used in SNMP already have such methods pre-registered by default. See `"register_pretty_printer"` for how new methods can be added. ### hex\_string() - convert OCTET STRING to hexadecimal notation. ### hex\_string\_of\_type() - convert octet string to hex, and check type against given tag. ### decode\_by\_template() - decode complex object according to a template. ``` ($var1, ...) = decode_by_template ($pdu, $template, ...); ``` The template can contain various `%X` 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. - %{ - 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. `"%99{"` will require a sequence tag of 99, or if the directive is given as `"%*{"`, the tag will be taken from the next argument. - %s - decode string - %i - decode integer - %u - decode unsigned integer - %O - decode Object ID (OID) - %A - decode IPv4 address - %@ - assigns the remaining undecoded part of the PDU to the next return value. ### decode\_sequence() - Split sequence into components. ``` ($first, $rest) = decode_sequence ($pdu); ``` Checks whether the PDU 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 PDU. ### 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. ## AUTHORS Created by: Simon Leinen \ Contributions and fixes by: - Andrzej Tobola \: Added long String decode - Tobias Oetiker \: Added 5 Byte Integer decode ... - Dave Rand \: Added "SysUpTime" decode - Philippe Simonet \: Support larger subids - Yufang HU \: Support even larger subids - Mike Mitchell \: New generalized "encode\_int()" - Mike Diehn \: "encode\_ip\_address()" - Rik Hoorelbeke \: "encode\_oid()" fix - Brett T Warden \: pretty "UInteger32" - Bert Driehuis \: Handle SNMPv2 exception codes - Jakob Ilves (/IlvJa) \: PDU decoding - Jan Kasprzak \: Fix for PDU syntax check - Milen Pavlov \: Recognize variant length for ints ## COPYRIGHT Copyright (c) 1995-2009, Simon Leinen. This program is free software; you can redistribute it under the "Artistic License 2.0" included in this distribution (file "Artistic").