asn1tools-js

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)