asn(3tcl)

📦

version 2.0 · 2 versions

2.0 · debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking (latest)
1.21 · debian bookworm, ubuntu jammy, ubuntu noble

, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 asn — ASN.1 BER encoder/decoder 💖

okay bestie, buckle up, this is the manual page for asn from the 3tcl manual, and it's giving extremely competent energy. no cap. it's long so we're doing it in parts, this is part one, let's go 🦋

✨ 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 🌈

so the asn package gives you partial de- and encoder commands for BER-encoded ASN.1 data, bestie. it can also be used for decoding DER, which is literally just a restricted subset of BER. slay.

ASN.1 is a standard Abstract Syntax Notation, and BER are its Basic Encoding Rules. iconic behavior honestly.

wanna know more about the standard? see http://asn1.elibel.tm.fr/en/standards/index.htm 🫶

also go look at 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 like… every implementor should read it, fr fr. 👑

💅 PUBLIC API 💅

🎀 ENCODER 🎀

::asn::asnSequence evalue... — takes zero or more encoded values, packs them into an ASN sequence, and hands you back its encoded binary form. 💖
::asn::asnSequenceFromList elist — same vibe, but it takes a list of encoded values, packs them into an ASN sequence, and returns the encoded binary form.
::asn::asnSet evalue... — takes zero or more encoded values, packs them into an ASN set, and returns its encoded binary form.
::asn::asnSetFromList elist — takes a list of encoded values, packs them into an ASN set, returns the encoded binary form. yes queen.
::asn::asnApplicationConstr appNumber evalue... — takes zero or more encoded values, packs them into an ASN application construct, and 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, and returns its encoded binary form.
::asn::asnChoiceConstr appNumber evalue... — takes zero or more encoded values, packs them into an ASN choice construct, and returns its encoded binary form.
::asn::asnInteger number — returns the encoded form of the integer number you gave it. 🍓
::asn::asnEnumeration number — returns the encoded form of the enumeration id number.
::asn::asnBoolean bool — returns the encoded form of the boolean value bool.
::asn::asnContext context data — takes an encoded value and packs it into a constructed value with application tag, the context number. (context is the number, data is the value.)
::asn::asnContextConstr context evalue... — takes zero or more encoded values and packs them into a constructed value with 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. don't come at it with one integer, it will not eat that. 💀
::asn::asnUTCTime utcstring — returns the encoded form of the UTC time string you passed.
::asn::asnNull — returns the NULL encoding. that's it. that's the whole thing. iconic minimalism. ✨
::asn::asnBitString string — returns the encoded form of the string.
::asn::asnOctetString string — returns the encoded form of the 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. so no funny business. 🙈
::asn::asnPrintableString string — returns the string encoded as ASN.1 PrintableString. raises an error if the string contains characters that aren't 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. 🎀
::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 an ASN.1 Basic Multilingual Plane string (which is essentially big-endian UCS2).
::asn::asnUTF8String string — returns the string encoded as a UTF8 String. heads up bestie: some legacy applications such as Windows CryptoAPI do not like UTF8 strings. if you're not sure, use BMPStrings. 💅
::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's more than one string type that could be used. see ::asn::defaultStringType.
::asn::defaultStringType ?type? — selects the string type to use for encoding non-ASCII strings. called with no argument, it returns the current default. if you do pass type, it should be either UTF8 or BMP, to choose UTF8String or BMPString respectively.

🦋 DECODER 🦋

general notes, bestie, read these before you touch anything:

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 gets stored. the remainder of the input after the decoded value gets stored back into the data variable.
after extraction the data variable is always modified first, before writing the extracted value to its variable. this means if both arguments refer to the same variable, it will always contain the extracted value after the call — not the remainder of the input. noted. 📝

::asn::asnPeekByte data_var byte_var — retrieves the first byte of the data without modifying data_var. great for checking implicit tags. peek, don't touch. 👀
::asn::asnGetLength data_var length_var — decodes the length information for a block of BER data. the tag has already got to be removed from the data before this.
::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 an encoded integer value is sitting 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. it also removes all bytes associated with the value from the data, so the following decoder commands can keep going. 🍓
::asn::asnGetEnumeration data_var enum_var — assumes 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. also strips all bytes associated with the value from the data for the next decoder commands.
::asn::asnGetOctetString data_var string_var — assumes a string is at the front of the data stored in data_var, stores it into the variable named by string_var, and removes all the bytes associated with the value from the data for the following decoder commands.
::asn::asnGetString data_var string_var ?type_var? — decodes a user-readable string. this is a convenience function that can 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 you pass the optional third argument type_var, then the type of the incoming string gets stored in the variable named by it.

heads up! this 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 necessary. no cap, that's your job to handle. 😭

::asn::asnGetNumericString data_var string_var — assumes a numeric string value is at the front of the data stored in the variable named data_var, stores it into the variable named by string_var, and removes all bytes associated with the value from the data for further processing by the following decoder commands.

okay so bestie, we're picking up right where we left off in the decoder bestie squad 💖 these commands are the ones that actually pull values out of the front of your data_var and yeet the consumed bytes so the next decoder can do its thing. no cap.

::asn::asnGetPrintableString data_var string_var — assumes a printable 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. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. printable string bestie, slay. ✨
::asn::asnGetIA5String data_var string_var — assumes an IA5 (ASCII) 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. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. ASCII core, periodt. 💅
::asn::asnGetBMPString data_var string_var — assumes a BMP (two-byte unicode) 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, converting it into a proper Tcl string. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. two-byte unicode ate. 🦋
::asn::asnGetUTF8String data_var string_var — assumes a UTF8 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, converting it into a proper Tcl string. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. UTF8, iconic. 🌈
::asn::asnGetUTCTime data_var utc_var — assumes a UTC time value is at the front of the data stored in the variable named data_var, and stores it into the variable named by utc_var. the UTC time value is stored as a string, which has to be decoded with the usual clock scan commands. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. clock scan bestie, iykyk. 🌸
::asn::asnGetBitString data_var bits_var — assumes a bit string value is at the front of the data stored in the variable named data_var, and stores it into the variable named by bits_var as a string containing only 0 and 1. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. binary baddie behavior. 💀
::asn::asnGetObjectIdentifier data_var oid_var — assumes a object identifier (OID) value is at the front of the data stored in the variable named data_var, and stores it into the variable named by oid_var as a list of integers. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. OID list of integers, fr fr. 🔥
::asn::asnGetBoolean data_var bool_var — assumes a boolean value is at the front of the data stored in the variable named data_var, and stores it into the variable named by bool_var. then it removes all bytes associated with the value from the data for further processing by the following decoder commands. true/false bestie. 💜
::asn::asnGetNull data_var — assumes a NULL value is at the front of the data stored in the variable named data_var and removes the bytes used to encode it from the data. null and void, but make it cute. 🙈
::asn::asnGetSequence data_var sequence_var — assumes an ASN sequence is at the front of the data stored in the variable named data_var, and stores it into the variable named by sequence_var. then it removes all bytes associated with the value from the data for further processing by the following decoder commands.
- The data in sequence_var is encoded binary and has to be further decoded according to the definition of the sequence, using the decoder commands here. so like, nested decoding energy. 🧚
::asn::asnGetSet data_var set_var — assumes an ASN set is at the front of the data stored in the variable named data_var, and stores it into the variable named by set_var. then it removes all bytes associated with the value from the data for further processing by the following decoder commands.
- 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 here. set bestie, slay. 🌸
::asn::asnGetApplication data_var appNumber_var ?content_var? ?encodingType_var? — assumes an ASN application construct is at the front of the data stored in the variable named data_var, and stores its id into the variable named by appNumber_var. then it removes all bytes associated with the value from the data for further processing by the following decoder commands.
- If a content_var is specified, then the command places all data associated with it into the named variable, in the binary form which can be processed using the decoder commands of this package.
- If a encodingType_var is specified, then that var is set to 1 if the encoding is constructed and 0 if it is primitive.
- Otherwise it is 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. so if you don't pass those vars, bestie, you're on your own — but like, with the package's decoder commands. 💅
::asn::asnGetContext data_var contextNumber_var ?content_var? ?encodingType_var? — assumes an ASN context tag construct is at the front of the data stored in the variable named data_var, and stores its id into the variable named by contextNumber_var. then it removes all bytes associated with the value from the data for further processing by the following decoder commands.
- If a content_var is specified, then the command places all data associated with it into the named variable, in the binary form which can be processed using the decoder commands of this package.
- If a encodingType_var is specified, then that var is set to 1 if the encoding is constructed and 0 if it is primitive.
- Otherwise it is the responsibility of the caller to decode the remainder of the construct based on the id retrieved by this command, using the decoder commands of this package. context bestie, you got this. 🫶

HANDLING TAGS 🎀

Working with ASN.1 you often need to decode tagged values, which use a tag thats different from the universal tag for a type. In those cases you have to replace the tag with the universal tag used for the type, to decode the value. To decode a tagged value use the ::asn::asnRetag to change the tag to the appropriate type to use one of the decoders for primitive values. To help with this the module contains three functions:

::asn::asnPeekTag data_var tag_var tagtype_var constr_var — the ::asn::asnPeekTag command can be used to take a peek at the data and decode the tag value, without removing it from the data. The tag_var gets set to the tag number, while the tagtype_var gets set to the class of the tag. (Either UNIVERSAL, CONTEXT, APPLICATION or PRIVATE). The constr_var is set to 1 if the tag is for a constructed value, and to 0 for not constructed. It returns the length of the tag. peekaboo bestie. 🙈
::asn::asnTag tagnumber ?class? ?tagstyle? — the ::asn::asnTag can be used to create a tag value. The tagnumber gives the number of the tag, while the class gives one of the classes (UNIVERSAL,CONTEXT,APPLICATION or PRIVATE). The class may be abbreviated to just the first letter (U,C,A,P), default is UNIVERSAL. The tagstyle is either C for Constructed encoding, or P for primitive encoding. 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. tag creation bestie, slay. ✨
::asn::asnRetag data_var newTag — replaces the tag in front of the data in data_var with newTag. The new Tag can be created using the ::asn::asnTag command. retag, glow up. 💅

EXAMPLES 🧚

Examples for the usage of this package can be found in the implementation of package ldap. okay so if you wanna see it in the wild, go peek at ldap. 🍓

BUGS, IDEAS, FEEDBACK 🫶

This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category asn of the Tcllib Trackers http://core.tcl.tk/tcllib/reportlist. Please also report any ideas for enhancements you may have for either package and/or documentation.

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

Note further that attachments are strongly preferred over inlined patches. Attachments can be made 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. we love a good bug report bestie. 😭

KEYWORDS 💜

asn, ber, cer, der, internet, protocol, x.208, x.209. these are the vibes. 💜

CATEGORY 🌈

Networking. periodt.

COPYRIGHT 👑

okay bestie that's the whole page 💖 source/version? it's tcllib, version 0.8, asn(3tcl) — the date didn't make it into the footer, but the icon energy is eternal. slay. ✨

📦 where this page comes from

debian trixie: tcllib 2.0+dfsg-4 · Tcl
ubuntu questing: tcllib 2.0+dfsg-4
ubuntu resolute: tcllib 2.0+dfsg-5 · Tcl
ubuntu stonking: tcllib 2.0+dfsg-6 · Tcl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms