ASN.1 Tools for TypeScript/JavaScript

A TypeScript implementation of ASN.1 (Abstract Syntax Notation One) encoding and decoding library, designed to be compatible with the Python asn1tools library. This library provides comprehensive support for message encoding/decoding in distributed systems and network protocols.

Features

• Full TypeScript Support: Written entirely in TypeScript with complete type definitions
• BER Encoding: Implements Basic Encoding Rules (BER) for ASN.1 encoding/decoding
• OER Encoding: Implements Octet Encoding Rules (OER) for compact, fixed-layout encoding
• Python Compatibility: API designed to match Python asn1tools for easy migration
• High Performance: Optimized for high-throughput message processing
• Comprehensive Testing: Extensive test coverage for reliability

Installation

npm install asn1tools-js

Quick Start

Basic Usage (BER — default)

import { compileString } from 'asn1tools-js';

const schema = `
  Messages DEFINITIONS ::= BEGIN
    DataRequest ::= SEQUENCE {
      messageId INTEGER,
      version INTEGER,
      category INTEGER,
      size INTEGER
    }
  END
`;

const spec = compileString(schema);

const encoded = spec.encode('DataRequest', {
  messageId: 123,
  version: 1,
  category: 2,
  size: 500
});

const decoded = spec.decode('DataRequest', encoded);

OER Encoding

OER produces a more compact, fixed-layout wire format. Pass { codec: 'oer' } when compiling:

import { compileString } from 'asn1tools-js';

const schema = `
  Messages DEFINITIONS ::= BEGIN
    BYTE  ::= INTEGER (-128..127)
    SHORT ::= INTEGER (-32768..32767)
    INT   ::= INTEGER (-2147483648..2147483647)
    LONG  ::= INTEGER (-9223372036854775808..9223372036854775807)

    SimpleMessage ::= SEQUENCE {
      id   LONG,
      flag BOOLEAN,
      data OCTET STRING (SIZE(20))
    }
  END
`;

const spec = compileString(schema, { codec: 'oer' });

const encoded = spec.encode('SimpleMessage', {
  id: 42n,
  flag: true,
  data: new Uint8Array(20).fill(0xAB)
});

const decoded = spec.decode('SimpleMessage', encoded);

Key differences from BER:

| Feature | BER | OER | |---------|-----|-----| | Encoding layout | Tag-Length-Value (TLV) | Fixed-width, no tag/length for known-size types | | Integer encoding | Variable-length, minimal octets | Fixed-width based on range constraint | | BOOLEAN | 3 bytes (tag + length + value) | 1 byte (0x00 / 0x01) | | SEQUENCE wrapper | Tag + length + members | Members concatenated directly | | SEQUENCE OF count | Wrapped in SEQUENCE TLV | OER length-determinant prefix | | CHOICE tag | BER context-specific tag | 1-byte index | | Single-pass encode | No (requires length pre-calculation) | Yes |

OER Wire Format

| ASN.1 Type | OER Encoding | |------------|-------------| | BOOLEAN | 1 byte (0x00 = false, 0x01 = true) | | INTEGER with range constraint | Fixed-width (1/2/4/8 bytes) based on range | | OCTET STRING (SIZE(N)) | N bytes, raw | | SEQUENCE | Concatenation of member encodings | | SEQUENCE OF | Length-determinant count + concatenated elements | | CHOICE | 1-byte tag index + selected alternative |

The OER length-determinant for SEQUENCE OF counts:

• 0-127: 1 byte (MSB=0, value in low 7 bits)
• 128+: first byte MSB=1, low 7 bits = number of following octets; then value in big-endian

Working with Binary Data

import { hexToBytes, bytesToHex } from 'asn1tools-js';

const identifier = hexToBytes('973539beb5008a29ca866b178ce99f2782b5e39a');
const hexString = bytesToHex(identifier);

Supported ASN.1 Types

| ASN.1 Type | TypeScript Mapping | Description | |------------|-------------------|-------------| | INTEGER | number \| bigint | Signed integers with automatic bigint handling | | BOOLEAN | boolean | True/false values | | OCTET STRING | Uint8Array | Binary data, identifiers, checksums | | NULL | null | Null values | | ENUMERATED | string | Named enumeration values | | SEQUENCE | object | Structured data objects | | SEQUENCE OF | Array<T> | Arrays of elements | | CHOICE | object | Union types with single active member |

API Reference

compileFiles(filenames: string[], options?: CompileOptions): Specification

Compiles ASN.1 files into a specification object.

const spec = compileFiles(['messages.asn'], { codec: 'oer' });

compileString(content: string, options?: CompileOptions): Specification

Compiles ASN.1 content from a string.

const spec = compileString(asnContent);             // BER (default)
const spec = compileString(asnContent, { codec: 'oer' }); // OER

CompileOptions

| Option | Type | Default | Description | |--------|------|---------|-------------| | codec | 'ber' \| 'oer' | 'ber' | Encoding rules to use |

Specification Methods

• encode(typeName: string, value: any): Uint8Array — Encode a value using the specified type
• decode(typeName: string, data: Uint8Array): any — Decode binary data using the specified type
• getTypeNames(): string[] — Returns all available type names
• getModuleNames(): string[] — Returns all available module names

Testing

npm test

The library includes comprehensive tests for both BER and OER:

• Unit Tests: Individual type encoding/decoding
• OER Tests: Primitives, SEQUENCE, SEQUENCE OF (short and long-form counts), CHOICE
• Integration Tests: Full message compilation and processing
• Cross-language Vectors: Hex test vectors for byte-level compatibility with other implementations

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• asn1tools - Python ASN.1 library (inspiration for this project)