0.1.0 • Published 8 years ago

x690 v0.1.0

Weekly downloads
5
License
ISC
Repository
github
Last release
8 years ago

x690

Low-level decoder for X.690 Distinguished Encoding Rules (DER). Tested with Node v5.9.1 and above.

Wikipedia has a decent explanation of DER. See also the full spec (PDF).

Installation

$ npm install --save x690

Usage

const x690 = require('x690')

const struct = x690.decodeStructure(someBuffer, 0)
if (struct.tagClass === x690.constants.UNIVERSAL && struct.primitive) {
  const value = x690.decodePrimitive(struct.type, someBuffer, struct.start, struct.length)
}

decodeStructure(buffer, offset)

Decodes an ASN.1 structure from buffer, starting at the given offset. Returns an object with the following properties:

  • start: offset within buffer at which the structure's value starts
  • end: offset within buffer at which the structure's value ends
  • length: length of the structure's value (in bytes)
  • primitive: true if the structure contains a primitive value, false otherwise
  • tagClass: one of the UNIVERSAL, APPLICATION, CONTEXT_SPECIFIC or PRIVATE constants
  • tagNumber: the tag number
  • type: if the tagClass is UNIVERSAL this will be one of the ASN.1 types (see constants), null otherwise

Note that decodeStructure() can be called with a partial buffer, provided the tag and length information is available. A RangeError is thrown if insufficient bytes are available.

decodePrimitive(type, buffer, offset, length)

Decodes a universal ASN.1 primitive value from buffer, starting at the given offset and with the given length. The value is determined by the type.

length may be 0 for the NULL and OCTET_STRING types, though it must still be provided. It must be 1 for the BOOLEAN type. It must be at least 1 for all other types.

An AssertionError or TypeError may be thrown if the value cannot be decoded. A RangeError is thrown if insufficient bytes are available.

The return values depend on the type:

TypeMinimum lengthMaximum lengthReturn value
BIT_STRING1Buffer
BMP_STRING1String
BOOLEAN11Boolean
CHARACTER_STRING1Buffer
ENUMERATED16Number
ENUMERATED7Buffer
GENERAL_STRING1String
GENERALIZED_TIME1519Date
GRAPHIC_STRING1String
IA5_STRING1String
INTEGER16Number
INTEGER7Buffer
NUMERIC_STRING1String
OBJECT_DESCRIPTOR1String
OBJECT_IDENTIFIER1String
OCTET_STRING0Buffer
PRINTABLE_STRING1String
REAL1Buffer
RELATIVE_OID1String
T61_STRING1String
UNIVERSAL_STRING1String
UTC_TIME1313Date
UTF8_STRING1String
VIDEOTEX_STRING1String
VISIBLE_STRING1String

constants

Tag classes and types are symbols. You can get a reference to these symbols through require('x690').constants and require('x690/constants').

Class symbols

  • UNIVERSAL
  • APPLICATION
  • CONTEXT_SPECIFIC
  • PRIVATE

Type symbols

  • BOOLEAN
  • INTEGER
  • BIT_STRING
  • OCTET_STRING
  • NULL
  • OBJECT_IDENTIFIER
  • OBJECT_DESCRIPTOR
  • EXTERNAL
  • REAL
  • ENUMERATED
  • EMBEDDED_PDV
  • UTF8_STRING
  • RELATIVE_OID
  • SEQUENCE
  • SET
  • NUMERIC_STRING
  • PRINTABLE_STRING
  • T61_STRING
  • VIDEOTEX_STRING
  • IA5_STRING
  • UTC_TIME
  • GENERALIZED_TIME
  • GRAPHIC_STRING
  • VISIBLE_STRING
  • GENERAL_STRING
  • UNIVERSAL_STRING
  • CHARACTER_STRING
  • BMP_STRING

Caveats

Currently this module only decodes DER data. It does a reasonable job of validating primitive values but the validation does not fully confirm to the X.690 specification. Figuring out how to validate the values can be tricky.

Validation may be improved in the future, even in patch releases. You should not assume that if you can parse a DER structure without errors that it is strictly valid.

Known exceptions

  • Fractional-second elements in GENERALIZED_TIME values are not checked for trailing zeros.

  • Other elements in GENERALIZED_TIME and UTC_TIME values, like the month, are only validated to be digits. The time is converted to an ISO 8601 structure and then parsed into a Date. This means x690 largely depends on the Date-parsing logic in the JavaScript engine.

  • GENERAL_STRING, GRAPHIC_STRING, T61_STRING, VIDEOTEX_STRING and VISIBLE_STRING values are treated as ASCII.

Note that this is likely not an exhaustive list. Please contribute any other exception you might come across.

Constructed values

This module only decodes primitive values. Other ASN.1 types, such as SEQUENCE and SET are constructed. There are rules around what constitutes a valid sequence and how its values must be sorted. This module does not concern itself with those rules.

Note that if you encounter such a type you can decodeStructure() to recursively decode each value.