ddn.crypto.encoding.asn1

ASN.1/DER encoding and decoding infrastructure.

Provides types and utilities for encoding and decoding data using Distinguished Encoding Rules (DER), a canonical subset of the Basic Encoding Rules (BER) for ASN.1.

Copyright

Copyright © 2025, Dejan Lekić

License

BSD-3-Clause
enum Asn1TagClass Asn1TagNumber
struct Asn1Tag Asn1Value DerReader
class DerWriter
fn appendBase128 decodeBase128 decodeOidToString decodeUnsignedInteger derDecodeLength derEncodeLength encodeOidFromString encodeUnsignedInteger formatUint parseUint

Types 6

enumAsn1TagClass : ubyte

ASN.1 tag class values.

The tag class occupies the two most significant bits of the tag byte.

UNIVERSAL = 0x00Universal class — defined by ASN.1 standard
APPLICATION = 0x40Application class — defined by the application
CONTEXT = 0x80Context-specific class — defined by the context (e.g. X.509)
PRIVATE = 0xC0Private class — defined by the user
enumAsn1TagNumber : ubyte

ASN.1 universal tag numbers.

These identify the data type within the UNIVERSAL class.

END_OF_CONTENT = 0x00End-of-content marker
BOOLEAN = 0x01Boolean value
INTEGER = 0x02Arbitrary-precision integer (signed, big-endian)
BIT_STRING = 0x03Bit string with optional unused-bit count
OCTET_STRING = 0x04Octet (byte) string
NULL = 0x05Null value (zero length)
OID = 0x06Object Identifier
UTF8_STRING = 0x0CUTF-8 encoded string
SEQUENCE = 0x10Ordered sequence of values
SET = 0x11Unordered set of values
PRINTABLE_STRING = 0x13Printable ASCII string
IA5_STRING = 0x16IA5 (ASCII) string
UTC_TIME = 0x17UTCTime (2-digit year)
GENERALIZED_TIME = 0x18GeneralizedTime (4-digit year)
structAsn1Tag

Represents an ASN.1 tag (class + constructed flag + tag number).

For simplicity, only single-byte tag encoding is supported (tag numbers 0–30), which covers all common cryptographic use cases.

Fields
Asn1TagClass tagClassThe tag class (UNIVERSAL, APPLICATION, CONTEXT, or PRIVATE).
ubyte tagNumberThe tag number within the class.
bool constructedWhether the value is constructed (contains child TLVs).
Methods
Asn1Tag sequence() pure nothrow @nogc @safeReturns a SEQUENCE tag (UNIVERSAL, constructed, number 0x10).
Asn1Tag set() pure nothrow @nogc @safeReturns a SET tag (UNIVERSAL, constructed, number 0x11).
Asn1Tag integer() pure nothrow @nogc @safeReturns an INTEGER tag (UNIVERSAL, primitive, number 0x02).
Asn1Tag bitString() pure nothrow @nogc @safeReturns a BIT STRING tag (UNIVERSAL, primitive, number 0x03).
Asn1Tag octetString() pure nothrow @nogc @safeReturns an OCTET STRING tag (UNIVERSAL, primitive, number 0x04).
Asn1Tag nullTag() pure nothrow @nogc @safeReturns a NULL tag (UNIVERSAL, primitive, number 0x05).
Asn1Tag oid() pure nothrow @nogc @safeReturns an OID tag (UNIVERSAL, primitive, number 0x06).
Asn1Tag contextTag(ubyte number, bool constructed = false) pure nothrow @nogc @safeCreates a context-specific tag with the given number.
ubyte encode() const pure nothrow @nogc @safeEncodes this tag as a single DER tag byte.
structAsn1Value

A TLV (Tag-Length-Value) container for ASN.1 data.

For primitive types, content holds the raw value bytes. For constructed types, content holds the concatenation of the encoded child TLVs.

Fields
Asn1Tag tagThe ASN.1 tag identifying the type and structure.
ubyte[] contentThe value bytes (or encoded children for constructed types).
Methods
Asn1Value sequence(ubyte[] content) pure @safeCreates a SEQUENCE Asn1Value with the given encoded child content.
Asn1Value integer(ubyte[] content) pure @safeCreates an INTEGER Asn1Value with the given signed big-endian content.
Asn1Value bitString(ubyte[] content, ubyte unusedBits = 0) pure @safeCreates a BIT STRING Asn1Value.
Asn1Value octetString(ubyte[] content) pure @safeCreates an OCTET STRING Asn1Value.
Asn1Value nullValue() pure nothrow @nogc @safeCreates a NULL Asn1Value (zero-length content).
Asn1Value oid(ubyte[] encodedOid) pure @safeCreates an OID Asn1Value with pre-encoded binary OID content.
ubyte[] derEncode() const @safeDER-encodes this TLV value.
classDerWriter

A builder for constructing DER-encoded ASN.1 structures.

Use the save / wrapSequence / wrapContext pattern to build constructed values: 

auto w = new DerWriter();
w.writeInteger(1);
w.writeOctetString([0x01, 0x02]);
auto pos = w.save();
w.wrapSequence(pos);
// buffer now holds SEQUENCE { INTEGER 1, OCTET STRING 0102 }

Fields
ubyte[] _buffer
Methods
ubyte[] wrapTlv(Asn1Tag tag, const(ubyte)[] content) pure @safeWraps `content` in a TLV with the given tag.
void writeInteger(const(ubyte)[] value)Writes a DER-encoded INTEGER from raw signed big-endian bytes.
void writeInteger(long value)Writes a DER-encoded INTEGER from a signed `long` value.
void writeOctetString(const(ubyte)[] value)Writes a DER-encoded OCTET STRING.
void writeBitString(const(ubyte)[] value, ubyte unusedBits = 0)Writes a DER-encoded BIT STRING.
void writeNull()Writes a DER-encoded NULL value (zero-length content).
void writeOid(const(ubyte)[] encodedOid)Writes a DER-encoded OID.
void writeBoolean(bool value)Writes a DER-encoded BOOLEAN.
void writeRaw(Asn1Tag tag, const(ubyte)[] content)Writes a raw TLV with an explicit tag and content.
size_t save() const pure nothrow @safeSaves the current write position for later wrapping.
void wrapSequence(size_t startPos)Wraps all bytes written since `startPos` in a SEQUENCE TLV.
void wrapContext(size_t startPos, ubyte tagNumber)Wraps all bytes written since `startPos` in a context-tagged TLV.
ubyte[] data() const pure nothrow @safeReturns a copy of the accumulated DER-encoded bytes.
void reset() pure nothrow @safeResets the writer to an empty state.
Constructors
this()Constructs an empty DerWriter.
structDerReader

Reads DER-encoded TLV values from a byte buffer.

Example: 

auto reader = DerReader(encodedBytes);
auto seq = reader.enterSequence();
auto intBytes = seq.readInteger();
auto octets   = seq.readOctetString();

Fields
const(ubyte)[] _data
size_t _pos
Methods
size_t position() @property const pure nothrow @safeThe current read position within the buffer.
size_t remaining() @property const pure nothrow @safeThe number of bytes remaining to be read.
Asn1Tag readTag()Reads the next ASN.1 tag from the buffer.
Asn1Value readTlv()Reads the next complete TLV value.
ubyte[] readInteger()Reads a DER INTEGER and returns its raw content bytes (signed, big-endian).
ubyte[] readOctetString()Reads a DER OCTET STRING and returns its content bytes.
ubyte[] readBitString(out ubyte unusedBits)Reads a DER BIT STRING and returns its data bytes.
void readNull()Reads and verifies a DER NULL value.
ubyte[] readOid()Reads a DER OID and returns its binary content bytes.
bool readBoolean()Reads a DER BOOLEAN.
DerReader enterConstructed(Asn1Tag expectedTag)Reads a constructed TLV with the expected tag and returns a new `DerReader` positioned over its content.
DerReader enterSequence()Enters a SEQUENCE, returning a reader over its content.
DerReader enterSet()Enters a SET, returning a reader over its content.
DerReader enterContext(ubyte tagNumber)Enters a constructed context-tagged TLV, returning a reader over its content.
void skip()Skips the next complete TLV value.
void verifyTag(ref Asn1Value tlv, Asn1Tag expected)Verifies that the TLV's tag matches the expected tag.
Constructors
this(const(ubyte)[] data)Constructs a reader over the given DER-encoded data.

Functions 10

fnubyte[] derEncodeLength(size_t length) pure @safeEncodes a length value using DER length encoding.
fnsize_t derDecodeLength(const(ubyte)[] data, out size_t bytesRead)Decodes a DER-encoded length from the start of a byte buffer.
fnubyte[] encodeUnsignedInteger(const(ubyte)[] bigEndianValue) pure @safeEncodes a non-negative integer as DER INTEGER content bytes.
fnubyte[] decodeUnsignedInteger(const(ubyte)[] content) pure @safeDecodes DER INTEGER content bytes to an unsigned big-endian representation.
fnubyte[] encodeOidFromString(string dotted) pure @safeEncodes an OID from its dotted-decimal string representation to binary.
fnstring decodeOidToString(const(ubyte)[] encoded) pure @safeDecodes a binary OID to its dotted-decimal string representation.
fnuint parseUint(string s) pure @safeParses a non-negative integer from a decimal string.
fnstring formatUint(uint value) pure @safeFormats a `uint` value as a decimal string.
fnvoid appendBase128(ref ubyte[] result, uint value) pure @safeAppends a single OID component value in base-128 encoding.
fnuint decodeBase128(const(ubyte)[] data, ref size_t pos) pure @safeDecodes one base-128-encoded OID component starting at `pos`.