or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-asn1

Contains parsers and serializers for ASN.1 (currently BER only)

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/asn1@0.2.x

To install, run

npx @tessl/cli install tessl/npm-asn1@0.2.0

index.mddocs/

ASN.1

ASN.1 is a pure JavaScript library for encoding and decoding ASN.1 (Abstract Syntax Notation One) datatypes using BER (Basic Encoding Rules). It provides both Reader and Writer classes for parsing and serializing ASN.1 data structures commonly used in cryptographic protocols, LDAP, SNMP, and X.509 certificates.

Package Information

  • Package Name: asn1
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install asn1

Core Imports

const { Ber, BerReader, BerWriter } = require('asn1');

Alternative import patterns:

// Access via Ber module
const asn1 = require('asn1');
const reader = new asn1.Ber.Reader(buffer);
const writer = new asn1.Ber.Writer();

// Direct class access
const { BerReader, BerWriter } = require('asn1');
const reader = new BerReader(buffer);
const writer = new BerWriter();

Basic Usage

Reading ASN.1 Data

const { BerReader, Ber } = require('asn1');

// Create reader from buffer
const buffer = Buffer.from([0x30, 0x03, 0x01, 0x01, 0xff]);
const reader = new BerReader(buffer);

// Read sequence
reader.readSequence();
console.log('Sequence len: ' + reader.length);

// Read boolean value
if (reader.peek() === Ber.Boolean) {
  console.log(reader.readBoolean()); // true
}

Writing ASN.1 Data

const { BerWriter } = require('asn1');

// Create writer
const writer = new BerWriter();

// Write sequence with boolean
writer.startSequence();
writer.writeBoolean(true);
writer.endSequence();

console.log(writer.buffer); // Buffer containing encoded data

Capabilities

ASN.1 BER Reader

Parses and reads ASN.1 BER encoded data from buffers.

/**
 * Creates a new BER reader for parsing ASN.1 data
 * @param {Buffer} data - Buffer containing BER encoded data
 */
class BerReader {
  constructor(data: Buffer);
  
  // Properties
  length: number;    // Length of current element being read
  offset: number;    // Current read position in buffer  
  remain: number;    // Remaining bytes in buffer
  buffer: Buffer;    // Remaining buffer from current offset
  
  // Reading methods
  readByte(peek?: boolean): number | null;
  peek(): number | null;
  readLength(offset?: number): number | null;
  readSequence(tag?: number): number | null;
  readInt(): number | null;
  readBoolean(): boolean | null;
  readEnumeration(): number | null;
  readString(tag?: number, retbuf?: boolean): string | Buffer | null;
  readOID(tag?: number): string | null;
}

ASN.1 BER Writer

Serializes and writes ASN.1 BER encoded data to buffers.

/**
 * Creates a new BER writer for generating ASN.1 data
 * @param {Object} options - Optional size and growth options
 */
class BerWriter {
  constructor(options?: object);
  
  // Properties
  get buffer(): Buffer;  // Generated BER data buffer (read-only)
  
  // Writing methods
  writeByte(b: number): void;
  writeInt(i: number, tag?: number): void;
  writeNull(): void;
  writeEnumeration(i: number, tag?: number): void;
  writeBoolean(b: boolean, tag?: number): void;
  writeString(s: string, tag?: number): void;
  writeBuffer(buf: Buffer, tag: number): void;
  writeStringArray(strings: string[]): void;
  writeOID(s: string, tag?: number): void;
  writeLength(len: number): void;
  
  // Sequence methods
  startSequence(tag?: number): void;
  endSequence(): void;
}

ASN.1 Type Constants

Constants for ASN.1 universal tags and flags.

// Universal ASN.1 types
const EOC = 0;              // End-of-contents
const Boolean = 1;          // Boolean type
const Integer = 2;          // Integer type
const BitString = 3;        // Bit string type
const OctetString = 4;      // Octet string type
const Null = 5;             // Null type
const OID = 6;              // Object identifier type
const ObjectDescriptor = 7; // Object descriptor type
const External = 8;         // External type
const Real = 9;             // Real/float type
const Enumeration = 10;     // Enumeration type
const PDV = 11;             // PDV type
const Utf8String = 12;      // UTF-8 string type
const RelativeOID = 13;     // Relative OID type
const Sequence = 16;        // Sequence type
const Set = 17;             // Set type
const NumericString = 18;   // Numeric string type
const PrintableString = 19; // Printable string type
const T61String = 20;       // T61 string type
const VideotexString = 21;  // Videotex string type
const IA5String = 22;       // IA5 string type
const UTCTime = 23;         // UTC time type
const GeneralizedTime = 24; // Generalized time type
const GraphicString = 25;   // Graphic string type
const VisibleString = 26;   // Visible string type
const GeneralString = 28;   // General string type
const UniversalString = 29; // Universal string type
const CharacterString = 30; // Character string type
const BMPString = 31;       // BMP string type

// Flags
const Constructor = 32;     // Constructor flag
const Context = 128;        // Context tag flag

Error Handling

Creates custom ASN.1 parsing errors.

/**
 * Creates a new InvalidAsn1Error with custom message
 * @param {string} message - Error message
 * @returns {Error} InvalidAsn1Error instance
 */
function newInvalidAsn1Error(message: string): Error;

Types

// Main module exports
interface ASN1Module {
  Ber: BerModule;
  BerReader: typeof BerReader;
  BerWriter: typeof BerWriter;
}

// BER sub-module
interface BerModule {
  Reader: typeof BerReader;
  Writer: typeof BerWriter;
  
  // Type constants (all number values)
  EOC: number;
  Boolean: number;
  Integer: number;
  BitString: number;
  OctetString: number;
  Null: number;
  OID: number;
  ObjectDescriptor: number;
  External: number;
  Real: number;
  Enumeration: number;
  PDV: number;
  Utf8String: number;
  RelativeOID: number;
  Sequence: number;
  Set: number;
  NumericString: number;
  PrintableString: number;
  T61String: number;
  VideotexString: number;
  IA5String: number;
  UTCTime: number;
  GeneralizedTime: number;
  GraphicString: number;
  VisibleString: number;
  GeneralString: number;
  UniversalString: number;
  CharacterString: number;
  BMPString: number;
  Constructor: number;
  Context: number;
  
  // Error function
  newInvalidAsn1Error: (message: string) => Error;
}

Error Handling

  • Reading Methods: Return null when insufficient data is available for reading
  • Invalid Data: Throws InvalidAsn1Error for malformed ASN.1 data structures
  • Type Validation: Throws TypeError for invalid arguments (non-Buffer input to Reader, etc.)
  • Buffer Management: Reader validates input with Buffer.isBuffer(), Writer automatically grows internal buffer

Usage Patterns

Reading Complex Structures

const { BerReader, Ber } = require('asn1');

function parseSequence(buffer) {
  const reader = new BerReader(buffer);
  const sequence = [];
  
  reader.readSequence();
  while (reader.offset < reader.length + 1) {
    const tag = reader.peek();
    
    if (tag === Ber.Integer) {
      sequence.push(reader.readInt());
    } else if (tag === Ber.Boolean) {
      sequence.push(reader.readBoolean());
    } else if (tag === Ber.OctetString) {
      sequence.push(reader.readString());
    }
  }
  
  return sequence;
}

Writing Complex Structures

const { BerWriter } = require('asn1');

function createSequence(values) {
  const writer = new BerWriter();
  
  writer.startSequence();
  
  for (const value of values) {
    if (typeof value === 'number') {
      writer.writeInt(value);
    } else if (typeof value === 'boolean') {
      writer.writeBoolean(value);
    } else if (typeof value === 'string') {
      writer.writeString(value);
    }
  }
  
  writer.endSequence();
  return writer.buffer;
}

Object Identifier (OID) Handling

const { BerWriter, BerReader } = require('asn1');

// Writing OID
const writer = new BerWriter();
writer.writeOID('1.2.840.113549.1.1.1'); // RSA encryption OID
const oidBuffer = writer.buffer;

// Reading OID
const reader = new BerReader(oidBuffer);
const oid = reader.readOID(); // '1.2.840.113549.1.1.1'