Generate and parse ASN1.BER objects
npm install asn1-ber**This project is a clone (not a fork) of the [asn1][asn1] project, and
as such is a drop in replacement. The [asn1][asn1] project has received little
attention over the past few years and is used in a number of heavily dependant
modules (one being my own [net-snmp][net-snmp] module), so I have committed to
maintaining this clone and for it to be a drop in replacement.**
[asn1]: https://github.com/mcavage/node-asn1
[net-snmp]: https://github.com/stephenwvickers/node-net-snmp
This module provides the ability to generate and parse ASN1.BER objects.
This module is installed using [node package manager (npm)][npm]:
npm install asn1-ber
It is loaded using the require() function:
var asn1 = require("asn1-ber")
A reader or writer can then be created to read or write objects:
// Let's create an ASN1.BER object using the writing interface:
var writer = new asn1.BerWriter()
writer.startSequence()
writer.writeBoolean(true)
writer.writeBoolean(false)
writer.endSequence()
var buffer = writer.buffer
// Now let's read the data back from the buffer:
var reader = new asn1.BerReader(buffer)
reader.readSequence()
reader.readBoolean() // first boolean is true
reader.readBoolean() // second boolean is false
It is assumed that users are somewhat familiar with ASN1 and BER encoding.
[nodejs]: http://nodejs.org "Node.js"
[npm]: https://npmjs.org/ "npm"
The following sections describe constants exported and used by this module.
This object contains constants which can be used wherever a tag parameter
can be provided. For example, the asn1.BerWriter.writeBoolean() method
accepts an optional tag parameter. In this method any of the following
constants could be used (or a number if the required type is not defined) to
specify the tag which be used when encoding the value, and in this particular
case would default to asn1.Ber.Boolean, e.g.:
writer.writeBoolean(true, asn1.Ber.Boolean)
The following constants are defined in this object:
* EOC
* Boolean
* Integer
* BitString
* OctetString
* Null
* OID
* ObjectDescriptor
* External
* Real
* Enumeration
* PDV
* Utf8String
* RelativeOID
* Sequence
* Set
* NumericString
* PrintableString
* T61String
* VideotexString
* IA5String
* UTCTime
* GeneralizedTime
* GraphicString
* VisibleString
* GeneralString
* UniversalString
* CharacterString
* BMPString
* Constructor
* Context
This module exposes two interfaces, one for reading ASN1.BER objects from
Node.js Buffer object instances, and another for writing ASN1.BER objects to
Node.js Buffer instances.
These two interfaces, and all their functions and methods, are documented in
seperate sections below.
ASN1.BER objects can be generated programatically using various methods. An
instance of the BerWriter class is instantiated and its methods used to do
this. Once an object is complete the associated Node.js Buffer object
instance can be obtained by accessing the buffer attribute of the BerWriter
object instance.
In the following example a simple sequence of two boolean objects is written,
then the Buffer instance obtained:
var writer = new asn1.BerWriter()
writer.startSequence()
writer.writeBoolean(true)
writer.writeBoolean(false)
writer.endSequence()
var buffer = writer.buffer
The resulting buffer will contain the following:
var buffer = Buffer.alloc([
asn1.Ber.Sequence | asn1.Ber.Constructor,
6, // length of the data contained within the sequence
asn1.Ber.Boolean,
1,
255, // true
asn1.Ber.Boolean,
1,
0, // false
)
Instantiates and returns an instance of the BerWriter class:
var options = {
size: 1024,
growthFactor: 8
}
var writer = new asn1.BerWriter(options)
The optional options parameter is an object, and can contain the following
items:
* size - The writer uses a Node.js Buffer instance to render ASN1.BER types
to a binary string, when creating the Buffer instance its size must be
specified, the size attribute specifies how bit this buffer should
initially be, when the Buffer instance has not space a new instance will
be created which will be larger than the original size specified, this
growth is controlled by the growthFactor variable, defaults to 1024
* growthFactor - When the Node.js Buffer instance used to render ASN1.BER
types to a binary string becomes full the Buffer instance will be made
larger, the size of the new instance is calculated using its current size
multiplied by the growthFactor attribute, defaults to 8, for example,
with a size of 1024 and a growthFactor of 8 when the Buffer
instance becomes full the new size would be calculated as 8192
Once an object is complete the Node.js Buffer instance can be obtained via the
writes buffer attribute, e.g.:
var buffer = writer.buffer
The Buffer instance returned will be a copy of the internal instance used by
the writer and can be safely modified once obtained.
The startSequence() method starts a new sequence. This method can be called
multiple times, and a matching call to the endSequence() method must be made
for each time startSequence() is called.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Sequence | asn1.Ber.Constructor.
The following example writes two sequences and a boolean, each nested in the
previous:
writer.startSequence()
writer.startSequence()
writer.writeBoolean()
writer.endSequence()
writer.endSequence()
The writeBoolean() method writes an object of type boolean.
The boolean parameter can be the values true or false. The optional tag
parameter is one of the constants defined in the asn1.Ber object, or a number
if the required type is not pre-defined, and defaults to asn1.Ber.Boolean.
The following example writes two different boolean values, and in one case thetag is specified as asn1.Ber.Integer:
writer.writeBoolean(false)
writer.writeBoolean(true, asn1.Ber.Integer)
The writerBuffer() method writes a Node.js Buffer instance as a sequence of
bytes, i.e. it will interpret it in any way.
The buffer parameter is an instance of the Node.js Buffer class. The
optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined. If no tag is
specified then buffer is assumed to already contain the tag and length for
the object to be written, i.e. it is assumed to contain a pre-formatted
ASN1.BER object such as a sequence, and will be inserted as is with no tag or
length.
The following two examples write a single byte in different ways. One provides
a tag, in which case writeBuffer() will write the tag and length, and in the
other no tag is provided, so writeBuffer() will NOT write a tag or length:
var b1 = Buffer.alloc([0x01])
writer.writeBuffer(b1, asn1.Ber.Integer)
var b2 = Buffer.alloc([asn1.Ber.Integer, 0x01, 0x01])
writer.writeBuffer(b2)
The writeByte() method writes a single byte, i.e. not tag or length are
written.
The byte parameter is an integer in the range 0 to 255.
The writeByte() method can be used to insert ad-hoc data into the data stream.
The following example writes the integer 2 using only the writeByte() method
instead of using the writeInt() method:
writer.writeByte(asn1.Ber.Integer) // tag
writer.writeByte(1) // length == 1
writer.writeByte(2) // integer == 2
The writeEnumeration() method writes the value of an enumerated type.
The integer parameter is the integer value of the enumerated type. The
optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Enumeration.
The following example writes the value 2 which identifies a value for an
enumerated type:
writer.writeEnumeration(2, asn1.Ber.Enumeration)
The writeInt() method writes a signed or unsigned integer.
The integer parameter is a signed or unsigned integer of 4 bytes in size. The
optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Integer.
The following example writes the value -123, and since no tag is provided the
type asn1.Ber.Integer will be used:
writer.writeInt(-123)
The writeNull() method writes 2 bytes, the first is the type asn1.Ber.Null
and the second is the 1 byte integer 0.
The following example writes a key and value pair, with the value being
specified as undefined using writeNull():
writer.writeString("description") // key is a string
writer.writeNull() // value is undefined
The writeOID() method writes an object identifier.
The oid parameter is an object identifier in the formar of 1.3.6.1, i.e.
dotted decimal. The optional tag parameter is one of the constants defined
in the asn1.Ber object, or a number if the required type is not pre-defined,
and defaults to asn1.Ber.OID.
The following example writes the object identifier 1.3.6.1, and since no tag
is provided the type asn1.Ber.OID will be used:
writer.writeOID("1.3.6.1")
The writeString() method writes a string.
The string parameter is a string, i.e. not a Node.js Buffer instance. The
optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.OctetString.
The following example writes the string description, and since no tag is
provided the type asn1.Ber.OctetString will be used:
writer.writeString("description")
The writeStringArray() method writes multiple strings by called thewriteString() method.
The strings parameter is an array of strings to pass when making repeated
calls to the writeString() method. The optional tag parameter is one of
the constants defined in the asn1.Ber object, or a number if the required
type is not pre-defined, and defaults to asn1.Ber.OctetString.
The following two examples are equivilant, and will both write two strings, and
since no tag is provided the type asn1.Ber.OctetString will be used:
writer.writeString("one")
writer.writeString("two")
writer.writeStringArray(["one", "two"])
The reader interface reads from a Node.js Buffer instance containing an
ASN1.BER object. A number of methods are used to read specific types of data,
also ensuring the required tags also exist for each. An instance of theBerReader class is instantiated, providing the constructor with a Node.jsBuffer instance, and methods used to do this.
As data is read from the Buffer instance an offset to the next location from
which to read data, i.e. following the last data read, is maintained and
incremented based on the amount of data read per method call.
In the following example the appropriate methods are used to read a buffer
containing an ASN1.BER object:
var buffer = Buffer.alloc([
asn1.Ber.Sequence | asn1.Ber.Constructor,
6, // length of the data contained within the sequence
asn1.Ber.Boolean,
1,
255, // true
asn1.Ber.Boolean,
1,
0, // false
)
var reader = new asn1.BerReader(buffer)
reader.readSequence(asn1.Ber.Sequence | asn1.Ber.Constructor)
reader.readBoolean() // 1st boolean is true
reader.readBoolean() // 2nd boolean is false
Instantiates and returns an instance of the BerReader class:
var reader = new asn1.BerReader(buffer)
The buffer parameter is an instance of the Node.js Buffer class, this is
typically referred to as the "input buffer" throughout this documentation.
The peek() method is sugar for the following method call:
var byte = reader.readByte(true)
The readBoolean() method reads a boolean value from the input buffer and
returns either true or false.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Boolean.
The following example reads a boolean value, since no tag is specified the
type asn1.Ber.Boolean is used to validate the type being read:
var bool = reader.readBoolean()
The readByte() method reads and returns the next byte from the input buffer,
and advances the read offset by 1.
The optional peek parameter, if passed as true, will cause the read offset
NOT to be incremented. This provides a way to look at the next byte in the
input stream without consuming it.
The following example reads a a boolean value if the next object is of the typeasn1.Ber.Boolean:
if (reader.readByte(true) == asn1.Ber.Boolean) {
reader.readByte() // consume the type
reader.readByte() // consume length, we assume 1, we /should/ really check
var value = reader.readByte() ? true : false
}
The readEnumeration() method reads an integer value of the enumerated type
and returns it.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Enumeration.
The following example reads an enumerated value, since no tag is specified the
type asn1.Ber.Enumeration is used to validate the type being read:
var integer = reader.readEnumeration()
The readEnumeration() method reads a signed or unsigned integer and returns
it.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.Integer.
The following example reads an integer value, since no tag is specified the
type asn1.Ber.Integer is used to validate the type being read:
var integer = reader.readInt()
The readOID() method reads an object identifier and returns it in the format1.3.6.1, i.e. in dotted decimal.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.OID.
The following example reads a object identifier, since no tag is specified the
type asn1.Ber.OID is used to validate the type being read:
var oid = reader.readOID()
The readSequence() method attempts to read the next sequence and its length
from the input buffer.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined. If no tag is
defined the type of the sequence is not verified and simply accepted.
If there was not enough data left in the input buffer to read the sequence thennull will be returned, otherwise the sequences type will be returned, i.e.
if tag was specified then the sequence type will be equal to tag.
The following example reads all sequences, each containing a key and value,
until there are no more sequences left:
var kvs = []
while (true) {
var tag = reader.readSequence() // We don't care about the sequences type
if (! tag)
break
var key = reader.readString()
var value = reader.readString()
kvs.push({key: key, value: value})
}
The readString() method reads a value from the input buffer, and if retbuf
is specified as true will return a Node.js Buffer instance containing the
bytes read, otherwise an attempt to parse the data as a utf8 string is made
and the resulting string will be returned, i.e. not a Buffer instance.
The optional tag parameter is one of the constants defined in the asn1.Ber
object, or a number if the required type is not pre-defined, and defaults toasn1.Ber.OctetString.
The following example reads a string and requests it be returned as a Buffer
instance:
var buffer = reader.readString(asn1.Ber.OctetString, true)
* Negative numbers are read when unsigned integers should be used in some
places
* The tag parameter to the Writer.writeBuffer() method in
lib/ber/writer.js should be optional so that pre-formatted buffers can be
written that already include a tag and length
* The license attribute is missing from package.json
* Create .npmignore file
* Correct names of error classes imported and used in lib/ber/writer.js
which result in not defined error messages
* Remove require(sys) statement from tst/ber/writer.test.js because it is
no longer supported or required
* Boolean logic error using instanceof in the writeStringArray() method in
lib/ber/writer.js
* Improve documentation
* Migrate tests to the mocha framework
* The tag parameter should be optional for methods which imply a type
* Sort out indentation and use tabs
* Minor changes to the README.md file
* The lib/ber/reader.js/Reader.prototype.readInt() method always uses the tag
type ASN1.Integer
* The lib/ber/reader.js/Reader.prototype.readEnumeration() method always uses
the tag type ASN1.Enumeration
* Added NoSpaceships Ltd as a maintainer
* Transfer to NoSpaceships github account
* Update author to NoSpaceships
* Remove redundant sections from README.md
* Change author and add write support for short OIDs
* Update buffer allocation to supported Buffer.alloc calls
* Fix zero-length octet string buffer writing
* Fix 5-byte integer encoding and decoding
* Remove modulo 2^32 on reading integers
* Allow no tag check on reading integers
* Add bit string reading
* Improve writeInt() function
Copyright (c) 2020 Mark Abrahams
Copyright (c) 2018 NoSpaceships Ltd
Copyright (c) 2017 Stephen Vickers
Copyright (c) 2011 Mark Cavage
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.