asn1-ts

ASN.1 TypeScript Library

• Author: Jonathan M. Wilbur <[e-mail]>
• Copyright Year: 2020
• License: MIT License

This library was based off of my D ASN.1 Library.

What is ASN.1?

ASN.1 stands for Abstract Syntax Notation. ASN.1 was first specified in X.680 - Abstract Syntax Notation One (ASN.1), by the International Telecommunications Union. ASN.1 messages can be encoded in one of several encoding/decoding standards. It provides a system of types that are extensible, and can presumably describe every protocol. You can think of it as a protocol for describing other protocols as well as a family of standards for encoding and decoding said protocols. It is similar to Google's Protocol Buffers, or Sun Microsystems' External Data Representation (XDR).

For more information on what ASN.1 is, see documentation/asn1.md.

Building

You can build this library by running npm run build. The outputs will all be in dist.

• dist/index.js is the root for usage in NodeJS.
• dist/asn1.min.js is the entire ASN.1 library for the web browser, which is minified, and accessible under the variable asn1.
• dist/ber.min.js is only the Basic Encoding Rules (BER), minified.
• dist/cer.min.js is only the Canonical Encoding Rules (CER), minified.
• dist/der.min.js is only the Distinguished Encoding Rules (DER), minified.

In many cases, you will only need one set of encoding rules or the other, so it is recommended to use either ber.min.js or der.min.js in your web application instead of asn1.min.js.

Library Usage

For each codec in the library, usage entails instantiating the class, then using that class' properties to get and set the encoded value. For all classes, the empty constructor creates an END OF CONTENT element. The remaining constructors will be codec-specific.

Here is a TypeScript example of encoding with Basic Encoding Rules, using the BERElement class.

let el : BERElement = new BERElement();
el.typeTag = ASN1UniversalType.integer;
el.integer = 1433; // Now the data is encoded.
console.log(el.integer); // Logs '1433'

... and here is how you would decode that same element:

let encodedData : Uint8Array = el.toBytes();
let el2 : BERElement = new BERElement();
el2.fromBytes(encodedData);
console.log(el2.integer); // Logs '1433'

Tests under the test directory can also serve as examples.

Future Development

• Encode REAL in Base-2 format in the DER encoder, because X.509 forbids base-10 encoding.
• Macros, like OPTIONAL<T>
• Encode a Set of elements as SET
• Support the new 2015 data types:
  • DATE
  • TIME-OF-DAY
  • DATE-TIME
  • DURATION
  • OID-IRI
  • RELATIVE-OID-IRI
• Implement these codecs:
  • Octet Encoding Rules (This is used by Simple Transportation Management Protocol (STMP) and DATEX-ASN.)
  • Canonical Octet Encoding Rules
  • NTCIP Encoding Rules (This is used by Simple Transportation Management Protocol (STMP) and DATEX-ASN.)
  • JSON Encoding Rules (May require changes to ASN1Element, or a separate element.)
  • Lightweight Encoding Rules (I cannot find a standard anywhere for this.)
  • BACNet Encoding Rules? (ISO 16484-5:2017)
  • Packed Encoding Rules
    • Basic Aligned Packed Encoding Rules (PER) (This is used by MCS / T.125, which is used by RDP. I believe it is also used by J2735 / DSRC.)
    • Basic Unaligned Packed Encoding Rules (UPER) (May require changes to ASN1Element) (Used by 3GPP RRC)
    • Canonical Aligned Packed Encoding Rules (CPER)
    • Canonical Unaligned Packed Encoding Rules (CUPER) (May require changes to ASN1Element)
• Internationalized strings.
• Document mistake of not returning number of bytes read for accessors.
• Serverless Functions
  • ValidateSize
  • ValidateRange
  • A function to encode almost every type.
  • A function to decode almost every type.
  • All things relating to JSON Encoding Rules.
• Compatibility-breaking changes
  • Error UUIDs.
  • Use the name field in errors.
  • Pass in the offending element into errors.
  • Use Uint8ClampedArray to represent BIT STRING.
  • Get rid of the codec-specific libraries.
  • Make TypeIdentifier a default export.
  • Make all functions use the macros instead of native types?

See Also

• X.680 - Abstract Syntax Notation One (ASN.1), published by the International Telecommunications Union.
• X.690 - BER, CER, and DER, published by the International Telecommunications Union.
• X.691 - Packed Encoding Rules.
• ASN.1: Communication Between Heterogeneous Systems by Olivier Dubuisson