asn(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

asn 💅✨

the ASN.1 BER encoder/decoder — manual page asn(n), bestie edition

okay so. before we do literally anything, let me just say: this is a Tcl package, asn, and it's the ASN.1 processing page from section n of the manual. she's long. she's iconic. buckle up 🎀

✨ NAME ✨

asn — ASN.1 BER encoder/decoder 🦋

✨ SYNOPSIS ✨

package require Tcl 8.5 9

package require asn ?0.8.5?

::asn::asnSequence evalue...

::asn::asnSequenceFromList elist

::asn::asnSet evalue...

::asn::asnSetFromList elist

::asn::asnApplicationConstr appNumber evalue...

::asn::asnApplication appNumber data

::asn::asnChoice appNumber evalue...

::asn::asnChoiceConstr appNumber evalue...

::asn::asnInteger number

::asn::asnEnumeration number

::asn::asnBoolean bool

::asn::asnContext context data

::asn::asnContextConstr context evalue...

::asn::asnObjectIdentifier idlist

::asn::asnUTCTime utcstring

::asn::asnNull

::asn::asnBitString string

::asn::asnOctetString string

::asn::asnNumericString string

::asn::asnPrintableString string

::asn::asnIA5String string

::asn::asnBMPString string

::asn::asnUTF8String string

::asn::asnString string

::asn::defaultStringType ?type?

::asn::asnPeekByte data_var byte_var

::asn::asnGetLength data_var length_var

::asn::asnGetResponse chan data_var

::asn::asnGetInteger data_var int_var

::asn::asnGetEnumeration data_var enum_var

::asn::asnGetOctetString data_var string_var

::asn::asnGetString data_var string_var ?type_var?

::asn::asnGetNumericString data_var string_var

::asn::asnGetPrintableString data_var string_var

::asn::asnGetIA5String data_var string_var

::asn::asnGetBMPString data_var string_var

::asn::asnGetUTF8String data_var string_var

::asn::asnGetUTCTime data_var utc_var

::asn::asnGetBitString data_var bits_var

::asn::asnGetObjectIdentifier data_var oid_var

::asn::asnGetBoolean data_var bool_var

::asn::asnGetNull data_var

::asn::asnGetSequence data_var sequence_var

::asn::asnGetSet data_var set_var

::asn::asnGetApplication     data_var     appNumber_var    ?content_var?
?encodingType_var?

::asn::asnGetContext    data_var     contextNumber_var     ?content_var?
?encodingType_var?

::asn::asnPeekTag data_var tag_var tagtype_var constr_var

::asn::asnTag tagnumber ?class? ?tagstyle?

::asn::asnRetag data_var newTag

✨ DESCRIPTION ✨

okay so the asn package hands you partial de- and encoder commands for BER-encoded ASN.1 data. and lowkey? you can also use it for decoding DER, which is just a restricted subset of BER. slay.

ASN.1 is a standard Abstract Syntax Notation, and BER are its Basic Encoding Rules. periodt. 💅

wanna know more about the standard? go look at http://asn1.elibel.tm.fr/en/standards/index.htm — that's the link, no notes.

also check out http://luca.ntop.org/Teaching/Appunti/asn1.html for A Layman's Guide to a Subset of ASN.1, BER, and DER, an RSA Laboratories Technical Note by Burton S. Kaliski Jr. (Revised November 1, 1993). a text version of this note is part of the module sources and should be read by any implementor. fr fr, not optional bestie. 📖✨

🌈 PUBLIC API 🌈

🎀 ENCODER 🎀

  • ::asn::asnSequence evalue... — takes zero or more encoded values, packs them into an ASN sequence, and returns its encoded binary form. 🫶
  • ::asn::asnSequenceFromList elist — same energy, but you hand her a list of encoded values instead. packs them into an ASN sequence and returns its encoded binary form.
  • ::asn::asnSet evalue... — takes zero or more encoded values, packs them into an ASN set, returns the encoded binary form. 💖
  • ::asn::asnSetFromList elist — takes a list of encoded values, packs them into an ASN set, returns the encoded binary form.
  • ::asn::asnApplicationConstr appNumber evalue... — takes zero or more encoded values, packs them into an ASN application construct, returns its encoded binary form.
  • ::asn::asnApplication appNumber data — takes a single encoded value data, packs it into an ASN application construct, returns its encoded binary form.
  • ::asn::asnChoice appNumber evalue... — takes zero or more encoded values, packs them into an ASN choice construct, returns its encoded binary form.
  • ::asn::asnChoiceConstr appNumber evalue... — takes zero or more encoded values, packs them into an ASN choice construct, returns its encoded binary form. (yes she's here too, matching energy 🦋)
  • ::asn::asnInteger number — returns the encoded form of the specified integer number.
  • ::asn::asnEnumeration number — returns the encoded form of the specified enumeration id number.
  • ::asn::asnBoolean bool — returns the encoded form of the specified boolean value bool. true/false girlie 💅
  • ::asn::asnContext context data — takes an encoded value and packs it into a constructed value with an application tag, the context number.
  • ::asn::asnContextConstr context evalue... — takes zero or more encoded values and packs them into a constructed value with an application tag, the context number.
  • ::asn::asnObjectIdentifier idlist — takes a list of at least 2 integers describing an object identifier (OID) value, and returns the encoded value. two minimum, no negotiating 🔥
  • ::asn::asnUTCTime utcstring — returns the encoded form of the specified UTC time string.
  • ::asn::asnNull — returns the NULL encoding. that's it. that's the whole job. iconic minimalism ✨
  • ::asn::asnBitString string — returns the encoded form of the specified string.
  • ::asn::asnOctetString string — returns the encoded form of the specified string.
  • ::asn::asnNumericString string — returns the string encoded as ASN.1 NumericString. raises an error if the string contains characters other than decimal numbers and space.
  • ::asn::asnPrintableString string — returns the string encoded as ASN.1 PrintableString. raises an error if the string contains characters which are not allowed by the Printable String datatype. the allowed characters are A-Z, a-z, 0-9, space, apostrophe, colon, parentheses, plus, minus, comma, period, forward slash, question mark, and the equals sign. that's the whole guest list, don't bring anyone else 🚫
  • ::asn::asnIA5String string — returns the string encoded as ASN.1 IA5String. raises an error if the string contains any characters outside of the US-ASCII range.
  • ::asn::asnBMPString string — returns the string encoded as ASN.1 Basic Multilingual Plane string (which is essentially big-endian UCS2).
  • ::asn::asnUTF8String string — returns the string encoded as UTF8 String. heads up bestie: some legacy applications such as Windows CryptoAPI do not like UTF8 strings. use BMPStrings if you are not sure. 🙈
  • ::asn::asnString string — returns an encoded form of string, choosing the most restricted ASN.1 string type possible. if the string contains non-ASCII characters, then there is more than one string type which can be used. see ::asn::defaultStringType.
  • ::asn::defaultStringType ?type? — selects the string type to use for the encoding of non-ASCII strings. returns the current default when called without an argument. if the argument type is supplied, it should be either UTF8 or BMP, to choose UTF8String or BMPString respectively. 💜

🦋 DECODER 🦋

general notes, listen up:

  1. nearly all decoder commands take two arguments. these arguments are variable names, except for ::asn::asnGetResponse. the first variable contains the encoded ASN value to decode at the beginning, and more, and the second variable is where the value is stored to. the remainder of the input after the decoded value is stored back into the datavariable. 📦
  2. after extraction the data variable is always modified first, before by writing the extracted value to its variable. this means that if both arguments refer to the same variable, it will always contain the extracted value after the call, and not the remainder of the input. (yeah, read that one twice, it's giving sneaky 💀)
  • ::asn::asnPeekByte data_var byte_var — retrieve the first byte of the data, without modifying data_var. this can be used to check for implicit tags. 👀
  • ::asn::asnGetLength data_var length_var — decode the length information for a block of BER data. the tag has already to be removed from the data.
  • ::asn::asnGetResponse chan data_var — reads an encoded ASN sequence from the channel chan and stores it into the variable named by data_var.
  • ::asn::asnGetInteger data_var int_var — assumes that an encoded integer value is at the front of the data stored in the variable named data_var, extracts it, and stores it into the variable named by int_var. additionally removes all bytes associated with the value from the data, for further processing by the following decoder commands.
  • ::asn::asnGetEnumeration data_var enum_var — assumes that an enumeration id is at the front of the data stored in the variable named data_var, and stores it into the variable named by enum_var. additionally removes all bytes associated with the value from the data, for further processing by the following decoder commands.
  • ::asn::asnGetOctetString data_var string_var — assumes that a string is at the front of the data stored in the variable named data_var, and stores it into the variable named by string_var. additionally removes all bytes associated with the value from the data, for further processing by the following decoder commands.
  • ::asn::asnGetString data_var string_var ?type_var? — decodes a user-readable string. this is a convenience function which is able to automatically distinguish all supported ASN.1 string types and convert the input value appropriately. see ::asn::asnGetPrintableString, ::asnGetIA5String, etc. below for the type-specific conversion commands.

if the optional third argument type_var is supplied, then the type of the incoming string is stored in the variable named by it.

the function throws the error "Invalid command name asnGetSomeUnsupportedString" if the unsupported string type Unsupported is encountered. you can create the appropriate function "asn::asnGetSomeUnsupportedString" in your application if neccessary. DIY era 🛠️✨

  • ::asn::asnGetNumericString data_var string_var — assumes that a numeric string value is at the front of the data stored in the variable named data_var, and stores it into the variable named by string_var. additionally removes all bytes associated with the value from the data, for further processing by the following decoder commands.
  • ::asn::asnGetPrintableString data_var string_var — okay so this one assumes a printable string value is chillin' right at the front of the data in the variable named data_var, and it drops it into the variable named by string_var 🎀. And bonus: it also yoinks out all the bytes that belonged to that value, so the next decoder command gets a nice clean front row ✨
  • ::asn::asnGetIA5String data_var string_var — same vibe, but for an IA5 (ASCII) string value at the front of data_var 💖 stores it in string_var, and again clears all the bytes associated with the value so the following decoder commands can keep going 🌸
  • ::asn::asnGetBMPString data_var string_var — this one's for a BMP (two-byte unicode) string value at the front of data_var 🦋 it goes into string_var and gets converted into a proper Tcl string, which is the glow-up we deserve. Then, yep, all the bytes for that value get removed for the following decoder commands 💅
  • ::asn::asnGetUTF8String data_var string_var — UTF8 string value at the front of data_var? Say less 💜 it lands in string_var, also converted into a proper Tcl string, and the bytes it used get removed so the following decoder commands aren't tripping over them ✨
  • ::asn::asnGetUTCTime data_var utc_var — assumes a UTC time value is up front in data_var and parks it in utc_var 🕰️ and heads up bestie, it's stored as a string, so you've gotta decode it with the usual clock scan commands, no cap. Bytes get removed like always, so the following decoder commands stay happy 🎀
  • ::asn::asnGetBitString data_var bits_var — bit string value at the front of data_var? It gets stored into bits_var as a string containing only 0 and 1 ⭐ iconic. Then all the bytes associated with the value get removed for the following decoder commands 🌈
  • ::asn::asnGetObjectIdentifier data_var oid_var — assumes an object identifier (OID) value is at the front of data_var 👑 it goes into oid_var as a list of integers, which is giving very organized. All the bytes for that value get removed so the following decoder commands can do their thing 💖
  • ::asn::asnGetBoolean data_var bool_var — boolean value at the front of data_var → straight into bool_var ✅ bytes removed, following decoder commands unbothered, periodt 🫶
  • ::asn::asnGetNull data_var — assumes a NULL value is at the front of the data in data_var, and it just removes the bytes used to encode it from the data 🕳️ no variable to store into, it's simply the cleanup crew 💅
  • ::asn::asnGetSequence data_var sequence_var — assumes an ASN sequence is at the front of data_var and stores it into sequence_var 🌸 all bytes associated with the value get removed so the following decoder commands can continue 💖

important lil note: the data in sequence_var is encoded binary, so you have to decode it further according to the definition of the sequence, using the decoder commands right here in this package 🦋

  • ::asn::asnGetSet data_var set_var — assumes an ASN set is at the front of data_var, stores it into set_var 🎀 bytes for that value get removed for the following decoder commands ✨

same energy as the sequence one: the data in set_var is encoded binary and has to be further decoded according to the definition of the set, using the decoder commands in here 💜

  • ::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var? — assumes an ASN application construct is at the front of the data in data_var and stores its id into appNumber_var 🔥 all the bytes associated with the value get removed for the following decoder commands 💖

If you pass a content_var, the command places all data associated with it into that named variable, in the binary form that can be processed using the decoder commands of this package 🦋

If you pass an encodingType_var, that var gets set to 1 if the encoding is constructed and 0 if it is primitive ⭐

Otherwise — and this is the part where you're on your own, bestie — it's the responsibility of the caller to decode the remainder of the application construct based on the id retrieved by this command, using the decoder commands of this package 💅

  • ::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var? — assumes an ASN context tag construct is at the front of data_var and stores its id into contextNumber_var 🌸 bytes associated with the value get removed for the following decoder commands 🎀

Pass a content_var and all data associated with it goes into that named variable, in the binary form processable with the decoder commands of this package ✨

Pass an encodingType_var and it's set to 1 when the encoding is constructed and 0 when it's primitive 💜

Otherwise it's the caller's responsibility to decode the remainder of the construct based on the id retrieved by this command, using the decoder commands of this package 👑

🌈 HANDLING TAGS 🌈

So when you're working with ASN.1, you'll often need to decode tagged values — and those use a tag that's different from the universal tag for that type 😭 in those cases you have to replace the tag with the universal tag used for the type, so the value can actually be decoded. To decode a tagged value, use ::asn::asnRetag to change the tag to the appropriate type, then use one of the decoders for primitive values 🦋

To help you out with all of this, the module contains three functions:

  • ::asn::asnPeekTag data_var tag_var tagtype_var constr_var — the ::asn::asnPeekTag command takes a lil peek at the data and decodes the tag value, without removing it from the data 👀 tag_var gets set to the tag number, and tagtype_var gets set to the class of the tag (either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE) 💖 constr_var gets set to 1 if the tag is for a constructed value and 0 if it's not constructed ✨ and it returns the length of the tag ⭐
  • ::asn::asnTag tagnumber ?class? ?tagstyle? — ::asn::asnTag creates a tag value for you 🎀 tagnumber gives the number of the tag, and class gives one of the classes (UNIVERSAL, CONTEXT, APPLICATION or PRIVATE) 🌸 the class can be abbreviated down to just the first letter (U, C, A, P), and the default is UNIVERSAL 💜 tagstyle is either C for Constructed encoding or P for primitve encoding, and it defaults to P 🦋 you can also use 1 instead of C and 0 instead of P for direct use of the values returned by ::asn::asnPeekTag 🔥
  • ::asn::asnRetag data_var newTag — replaces the tag in front of the data in data_var with newTag 💅 and newTag can be created using the ::asn::asnTag command ✨

🎀 EXAMPLES 🎀

Want to see this package in action? Examples for the usage of this package can be found in the implementation of package ldap 👑 go look, it's right there, free real estate 💖

😭 BUGS, IDEAS, FEEDBACK 😭

Real talk: this document, and the package it describes, will undoubtedly contain bugs and other problems 🙈 that's just how it is. Please report such in the category asn of the Tcllib Trackers at http://core.tcl.tk/tcllib/reportlist 🫶

Please also report any ideas for enhancements you may have for either the package and/or the documentation — we want them, fr fr 💜

When proposing code changes, please provide unified diffs, i.e the output of diff -u ✨

Also note, and this one matters: attachments are strongly preferred over inlined patches 💅 you can make attachments by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar 🎀

⭐ KEYWORDS ⭐

asn, ber, cer, der, internet, protocol, x.208, x.209

🌸 CATEGORY 🌸

Networking

  • Copyright (c) 2004 Andreas Kupries <andreas_kupries@users.sourceforge.net>
  • Copyright (c) 2004 Jochen Loewer <loewerj@web.de>
  • Copyright (c) 2004-2011 Michael Schlenker <mic42@users.sourceforge.net>

and that's a wrap bestie 🫶 this was asn(n) from tcllib version 0.8 — go decode something cute, ily, mwah 💅✨🎀

📦 where this page comes from