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:

Type|Minimum length|Maximum length|Return value ---|---|---|--- BIT_STRING|1|∞|Buffer BMP_STRING|1|∞|String BOOLEAN|1|1|Boolean CHARACTER_STRING|1|∞|Buffer ENUMERATED|1|6|Number ENUMERATED|7|∞|Buffer GENERAL_STRING|1|∞|String GENERALIZED_TIME|15|19|Date GRAPHIC_STRING|1|∞|String IA5_STRING|1|∞|String INTEGER|1|6|Number INTEGER|7|∞|Buffer NUMERIC_STRING|1|∞|String OBJECT_DESCRIPTOR|1|∞|String OBJECT_IDENTIFIER|1|∞|String OCTET_STRING|0|∞|Buffer PRINTABLE_STRING|1|∞|String REAL|1|∞|Buffer RELATIVE_OID|1|∞|String T61_STRING|1|∞|String UNIVERSAL_STRING|1|∞|String UTC_TIME|13|13|Date UTF8_STRING|1|∞|String VIDEOTEX_STRING|1|∞|String VISIBLE_STRING|1|∞|String

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.