x690

    0.1.0 • Public • Published

    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.

    Install

    npm i x690

    DownloadsWeekly Downloads

    20

    Version

    0.1.0

    License

    ISC

    Last publish

    Collaborators

    • novemberborn