BER(3pm)

💖 BER(3pm) 💖

okay so this is the BER page from the User Contributed Perl Documentation set, and bestie, it's literally the whole manual for BER.pm. Let's get into it 🦋

---

✨ NAME ✨

BER — the Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1). yes the acronyms are unhinged, we move 💅

---

✨ 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".

like. look at it. encode a thing, decode a thing, done. iconic behaviour 👑

---

✨ DESCRIPTION ✨

so this is a simple library for encoding and decoding data using the Basic Encoding Rules (BER) of Abstract Syntax Notation One (ASN.1) 🎀

ngl, it does not claim to be a complete implementation of the standard. it is not trying to be the main character of ASN.1. what it does do is implement enough of the BER standard to encode and decode SNMP messages — and that's the whole vibe check 💜

---

✨ VARIABLES ✨

• $pretty_print_timeticks (default: 1) — if it's non-zero (and babes, the default is non-zero), 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 that's more your thing, bind $pretty_print_timeticks to zero 🫶

• $errmsg — error message from last failed operation.

when they hit errors, the routines in this module will generally return "undef") and leave an informative error message in $errmsg). so like, check it, fr fr 😭

---

✨ METHODS ✨

🌸 encode_int_0() — encode the integer 0.

this is functionally identical to encode_int(0). that's it. that's the function 🍓

🌸 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 gets used e.g. in binding lists for variables that don't have a value (yet) 🙈

🌸 encode_sequence() and encode_tagged_sequence()

$encoded = encode_sequence (encoded1, encoded2, ...);
$encoded = encode_tagged_sequence (tag, encoded1, encoded2, ...);

these take already encoded values and extend them into an encoded sequence ✨

encoded_sequence uses the generic sequence tag, while with encode_tagged_sequence you get to specify your own tag — custom tag, your rules 💅

🌸 encode_string() — encode a Perl string as an OCTET STRING.

🌸 encode_ip_address() — encode an IPv4 address.

you can pass it either 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 a 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 come back as a sequence, in the order of the directives that generated them ✨

• %{ — decode sequence.

this doesn't assign any return value, it 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 <simon.leinen@switch.ch> 💜

Contributions and fixes by:

• Andrzej Tobola <san@iem.pw.edu.pl>: Added long String decode
• Tobias Oetiker <tobi@oetiker.ch>: Added 5 Byte Integer decode ...
• Dave Rand <dlr@Bungi.com>: Added "SysUpTime" decode
• Philippe Simonet <sip00@vg.swissptt.ch>: Support larger subids
• Yufang HU <yhu@casc.com>: Support even larger subids
• Mike Mitchell <Mike.Mitchell@sas.com>: New generalized "encode_int()"
• Mike Diehn <mdiehn@mindspring.net>: "encode_ip_address()"
• Rik Hoorelbeke <rik.hoorelbeke@pandora.be>: "encode_oid()" fix
• Brett T Warden <wardenb@eluminant.com>: pretty "UInteger32"
• Bert Driehuis <driehuis@playbeing.org>: Handle SNMPv2 exception codes
• Jakob Ilves (/IlvJa) <jakob.ilves@oracle.com>: PDU decoding
• Jan Kasprzak <kas@informatics.muni.cz>: Fix for PDU syntax check
• Milen Pavlov <milen@batmbg.com>: Recognize variant length for ints

every single one of them ate, no crumbs 👑✨

---

✨ 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").

💖 quick heads up bestie: that's the Artistic License 2.0, and the license text lives in the file literally named "Artistic" in this distribution. go read it, it's giving legal but make it cute 🎀

---

and that's the whole page!! this one shipped as part of perl v5.36.0, dated 2023-06-16, and it's filed under BER(3pm) in the User Contributed Perl Documentation. mwah, go decode something 🌸💅🦋