Tcl Library Source Code

Documentation
Login


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

asn - ASN.1 BER encoder/decoder

Table Of Contents

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

The asn package provides partial de- and encoder commands for BER encoded ASN.1 data. It can also be used for decoding DER, which is a restricted subset of BER.

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

See http://asn1.elibel.tm.fr/en/standards/index.htm for more information about the standard.

Also see 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.

PUBLIC API

ENCODER

DECODER

General notes:

  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.

  3. ::asn::asnPeekByte data_var byte_var

    Retrieve the first byte of the data, without modifing data_var. This can be used to check for implicit tags.

  4. ::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.

  5. ::asn::asnGetResponse chan data_var

    Reads an encoded ASN sequence from the channel chan and stores it into the variable named by data_var.

  6. ::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 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.

  7. ::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.

  8. ::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.

  9. ::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 asnGetSome__UnsupportedString__" if the unsupported string type Unsupported is encountered. You can create the appropriate function "asn::asnGetSome__UnsupportedString__" in your application if neccessary.

  10. ::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.

  11. ::asn::asnGetPrintableString data_var string_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  12. ::asn::asnGetIA5String data_var string_var

    Assumes that a 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  13. ::asn::asnGetBMPString data_var string_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  14. ::asn::asnGetUTF8String data_var string_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  15. ::asn::asnGetUTCTime data_var utc_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  16. ::asn::asnGetBitString data_var bits_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  17. ::asn::asnGetObjectIdentifier data_var oid_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  18. ::asn::asnGetBoolean data_var bool_var

    Assumes that 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. Additionally removes all bytes associated with the value from the data for further processing by the following decoder commands.

  19. ::asn::asnGetNull data_var

    Assumes that 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.

  20. ::asn::asnGetSequence data_var sequence_var

    Assumes that 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. Additionally 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.

  21. ::asn::asnGetSet data_var set_var

    Assumes that 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. Additionally 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.

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

    Assumes that 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. Additionally 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.

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

    Assumes that 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. Additionally 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.

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:

EXAMPLES

Examples for the usage of this package can be found in the implementation of package 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. 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.

KEYWORDS

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

CATEGORY

Networking

COPYRIGHT

Copyright © 2004 Andreas Kupries
Copyright © 2004 Jochen Loewer
Copyright © 2004-2011 Michael Schlenker