Skip to content

CDecoder

Jay edited this page Oct 3, 2026 · 2 revisions

CDecoder

#include <certpp/asn1/decoder.hpp> --- certpp::asn1

Represents an ASN.1 decoder. This provides static methods for decoding ASN.1 data.

Methods

static bool readEncodedValue( const TReadOnlySpan<uint8_t>& source, EEncodingRule ruleSet, CTag& outTag, TReadOnlySpan<uint8_t>& outArea, size_t& bytesRead )

Tries to read an encoded ASN.1 value from the source span.

  • source --- The source span containing ASN.1 encoded data.
  • ruleSet --- The ASN.1 encoding rule set to use.
  • outTag --- The output tag of the encoded value.
  • outArea --- The output span containing the encoded value.
  • bytesRead --- The number of bytes consumed from the source span.

Returns: True if an encoded value was successfully read; otherwise, false.

static EDecoderStatus tryReadEncodedValue( const TReadOnlySpan<uint8_t>& source, EEncodingRule ruleSet, CTag& outTag, TReadOnlySpan<uint8_t>& outArea, size_t& bytesRead )

Reads an encoded ASN.1 value, reporting why a read did not succeed.

The same operation as readEncodedValue() above, which is this call compared against EDEC_OK. It exists because the distinction between a value that is merely incomplete and one that is malformed cannot be recovered from a bool, and a caller feeding bytes in as they arrive -- off a socket, or a stream -- has to make exactly that decision: EDEC_NEED_MORE means read more and call again with a longer span, and every other non-OK status means this input will never parse no matter how much is appended.

Note what EDEC_NEED_MORE does not tell you: how many more bytes. The length octets may themselves be the part that is truncated, in which case the total is not yet knowable.

  • source --- The source span containing ASN.1 encoded data.
  • ruleSet --- The ASN.1 encoding rule set to use.
  • outTag --- The output tag of the encoded value. Only meaningful on EDEC_OK.
  • outArea --- The output span containing the encoded value's content. Only meaningful on EDEC_OK. Note this is the content, while bytesRead covers tag, length and content -- iterating by the span descends into a constructed value, iterating by bytesRead steps over it.
  • bytesRead --- The number of bytes consumed from the source span. Only meaningful on EDEC_OK.

Returns: EDEC_OK on success. EDEC_BAD_ARGS for an unknown ruleSet or a tag that cannot be decoded at all. EDEC_NEED_MORE if the source ends before the value does. EDEC_RESERVED for the reserved 0xFF length form, EDEC_TOO_BIG for a length (or an indefinite-length nesting depth) beyond what this decoder will process, and EDEC_PROHIBITED for an encoding the chosen rule set forbids -- an indefinite length under DER, or a CER segment over its own limit.

static bool readNextElement( TReadOnlySpan<uint8_t>& cursor, EEncodingRule ruleSet, CTag& outTag, TReadOnlySpan<uint8_t>& outArea )

Reads the next encoded ASN.1 value from a SEQUENCE/SET's content, advancing the cursor past it. Used to iterate a constructed value's members: pass the outArea of an outer readEncodedValue() call, then call this repeatedly until cursor is empty.

  • cursor --- The remaining content to read from; advanced past the value read on success.
  • ruleSet --- The ASN.1 encoding rule set to use.
  • outTag --- The output tag of the encoded value.
  • outArea --- The output span containing the encoded value's content.

Returns: True if a value was successfully read; false on a parse error or if cursor was empty.

static bool decodeBoolean(SReadOnlyByteSpan content, EEncodingRule ruleSet, bool& outValue)

Decodes a BOOLEAN's content octets.

  • content --- The content octets (exactly 1 octet).
  • ruleSet --- The ASN.1 encoding rule set to use; EAENC_DER/EAENC_CER require the canonical 0x00 (false) / 0xFF (true) values, while EAENC_BER accepts any octet.
  • outValue --- The decoded value.

Returns: True if content was a valid BOOLEAN encoding; otherwise, false.

static bool decodeInteger(SReadOnlyByteSpan content, int64_t& outValue)

Decodes an INTEGER's content octets into a 64-bit signed integer.

  • content --- The content octets (a minimal-length two's-complement big-endian integer).
  • outValue --- The decoded value.

Returns: True if content was a valid INTEGER encoding representable in an int64_t; otherwise, false.

static bool decodeEnumerated(SReadOnlyByteSpan content, uint32_t& outValue)

Decodes an ENUMERATED's content octets into a 32-bit unsigned integer.

  • content --- The content octets (encoded identically to INTEGER).
  • outValue --- The decoded value.

Returns: True if content was a valid, non-negative ENUMERATED encoding representable in a uint32_t; otherwise, false.

static bool decodeNull(SReadOnlyByteSpan content)

Validates a NULL's content octets.

  • content --- The content octets (must be empty).

Returns: True if content was a valid NULL encoding; otherwise, false.

static bool decodeOctetString(SReadOnlyByteSpan content, SReadOnlyByteSpan& outValue)

Decodes an OCTET STRING's content octets. Any byte sequence is valid, so this is a validating pass-through, provided for symmetry with the other decode*() methods.

  • content --- The content octets.
  • outValue --- The decoded value (aliases content).

Returns: Always true.

static bool decodeOctetString(SReadOnlyByteSpan content, COctet& outValue)

Decodes an OCTET STRING's content octets into an owning COctet, copying the content rather than aliasing it like the SReadOnlyByteSpan overload does.

  • content --- The content octets.
  • outValue --- The decoded value, replacing any content it previously held.

Returns: True if content was successfully copied into outValue; otherwise, false.

static bool decodeBitString(SReadOnlyByteSpan content, SReadOnlyByteSpan& outBits, uint8_t& outUnusedBits)

Decodes a BIT STRING's content octets.

  • content --- The content octets (an unused-bit count octet followed by the packed bits).
  • outBits --- The packed bit data octets (aliases content, excluding the unused-bit count octet).
  • outUnusedBits --- The number of unused (padding) bits in the last octet of outBits (0-7).

Returns: True if content was a valid BIT STRING encoding (including that any padding bits are zero); otherwise, false.

static bool decodeBitString(SReadOnlyByteSpan content, COctet& outBits, uint8_t& outUnusedBits)

Decodes a BIT STRING's content octets into an owning COctet, copying the packed bit data rather than aliasing it like the SReadOnlyByteSpan overload does.

  • content --- The content octets (an unused-bit count octet followed by the packed bits).
  • outBits --- The decoded packed bit data, replacing any content it previously held.
  • outUnusedBits --- The number of unused (padding) bits in the last octet of outBits (0-7).

Returns: True if content was a valid BIT STRING encoding and was successfully copied into outBits; otherwise, false.

static bool testNamedBit(SReadOnlyByteSpan content, uint32_t bitIndex)

Tests a single named bit of a BIT STRING used as a NamedBitList (e.g. X.509's KeyUsage). A bit beyond the encoded content is implicitly unset, per X.690 22.5.

  • content --- The BIT STRING's content octets.
  • bitIndex --- The zero-based named bit position to test.

Returns: True if content was a valid BIT STRING and bitIndex is set; otherwise, false.

static size_t countOidArcs(SReadOnlyByteSpan content)

Counts the number of subidentifiers (arcs) an OBJECT IDENTIFIER's content decodes to, so a caller can size the buffer passed to decodeOid().

  • content --- The content octets.

Returns: The arc count, or 0 if content is not a valid OBJECT IDENTIFIER encoding.

static bool decodeOid(SReadOnlyByteSpan content, TSpan<uint32_t> outArcs, size_t& outArcCount)

Decodes an OBJECT IDENTIFIER's content octets into its arc values.

  • content --- The content octets.
  • outArcs --- The destination for the decoded arc values; must be at least countOidArcs(content) long.
  • outArcCount --- The number of arcs written to outArcs.

Returns: True if content was a valid OBJECT IDENTIFIER encoding that fit in outArcs; otherwise, false.

template<typename TChar> static bool decodeOidString(SReadOnlyByteSpan content, TString<TChar>& outValue)

Decodes an OBJECT IDENTIFIER's content octets directly into its dotted-decimal text form (e.g. "1.2.840.113549.1.1.1"), rather than a raw arc array. Only ever produces ASCII digits and '.' separators, so unlike decodeString() this is locale-independent for both TChar=char and TChar=wchar_t -- it never goes through TUtf8Encoding. @tparam TChar The destination TString's character type (char or wchar_t).

  • content --- The content octets.
  • outValue --- The decoded dotted-decimal text. Left unchanged if this returns false.

Returns: True if content was a valid OBJECT IDENTIFIER encoding with at most MAX_OID_TEXT_ARCS arcs and was successfully formatted; otherwise, false.

static bool decodeText(SReadOnlyByteSpan content, EUniversalTags kind, SReadOnlyByteSpan& outText)

Decodes/validates a character string type's content octets.

  • content --- The content octets.
  • kind --- The universal string tag (EAUTAG_STRING_UTF8, EAUTAG_STRING_P, EAUTAG_STRING_IA5, or EAUTAG_STRING_N get their character set validated; any other tag is passed through unvalidated).
  • outText --- The decoded text (aliases content).

Returns: True if content is valid for kind's character set; otherwise, false.

template<typename TChar> static bool decodeString(SReadOnlyByteSpan content, EUniversalTags kind, TString<TChar>& outValue)

Decodes/validates a character string type's content octets directly into a TString, rather than a raw byte span. Validates via decodeText() (so the same kinds get their character set checked), then transcodes the validated bytes into TChar through TUtf8Encoding -- valid for any kind, since a kind whose charset decodeText() restricts to plain ASCII (PrintableString, IA5String, NumericString) is inherently already valid UTF-8 too (ASCII is a byte-identical subset of UTF-8).

TChar=wchar_t transcodes genuine UTF-8 regardless of the process locale. TChar=char instead goes through TUtf8Encoding, which treats char as native-locale text (not raw UTF-8) -- so non-ASCII content only round-trips correctly under a UTF-8-compatible locale; under "C", only the ASCII subset decodes as expected. @tparam TChar The destination TString's character type (char or wchar_t).

  • content --- The content octets.
  • kind --- The universal string tag; see decodeText() for which kinds get validated.
  • outValue --- The decoded string. Left unchanged if this returns false.

Returns: True if content is valid for kind's character set and was successfully transcoded to TChar; otherwise, false.

static bool decodeUtcTime(SReadOnlyByteSpan content, SDateTime& outTime)

Decodes a UTCTime's content octets (the DER-canonical "YYMMDDHHMMSSZ" form).

  • content --- The content octets (exactly 13 bytes).
  • outTime --- The decoded time.

Returns: True if content was a valid UTCTime encoding; otherwise, false.

static bool decodeGeneralizedTime(SReadOnlyByteSpan content, SDateTime& outTime)

Decodes a GeneralizedTime's content octets (the "YYYYMMDDHHMMSS[.fff]Z" form).

  • content --- The content octets.
  • outTime --- The decoded time.

Returns: True if content was a valid GeneralizedTime encoding; otherwise, false.

static bool decodeDistinguishedName(SReadOnlyByteSpan content, CDistinguishedName& outValue)

Decodes a CDistinguishedName (X.501 Name/RDNSequence) from a SEQUENCE's content octets, i.e. the content of an outer SEQUENCE tag-length-value (see CReader's readDistinguishedName() for reading that outer tag from a stream too).

Each content element must be a SET (RelativeDistinguishedName) containing exactly one AttributeTypeAndValue -- a multi-valued RDN is rejected, since CDistinguishedName only ever holds one CName per ENameType. Each AttributeTypeAndValue's type must be one of the X.520 OIDs CName::attributeTypeOf() recognizes, and its value must be a PrintableString or UTF8String (the two kinds CEncoder::encodeDistinguishedName() ever writes); any other structure or value kind fails the decode.

Always applies DER's encoding rules, regardless of the enclosing document's rule set -- in practice, X.501 Names are encoded with DER even inside a BER/CER document.

  • content --- The content octets of the outer SEQUENCE (RDNSequence).
  • outValue --- The decoded distinguished name, replacing any content it previously held. Left unchanged if this returns false.

Returns: True if content was a valid, supported RDNSequence encoding; otherwise, false.

Example

Reads a DER document's outer SEQUENCE and walks its members. The output span is the value's content octets, while bytesRead counts the tag and length too -- so iterating with the span is what descends into a constructed value, and iterating with bytesRead is what steps over it.

// given: SReadOnlyByteSpan der
CTag tag;
SReadOnlyByteSpan content;
size_t bytesRead = 0;

if (!CDecoder::readEncodedValue(der, EAENC_DER, tag, content, bytesRead)) {
    return;
}

if (tag != CTag(CTag::SEQ)) {
    return;
}

SReadOnlyByteSpan cursor = content;
CTag childTag;
SReadOnlyByteSpan childContent;

while (CDecoder::readNextElement(cursor, EAENC_DER, childTag, childContent)) {
    int64_t number = 0;
    if (childTag == CTag(CTag::INTEGER) && CDecoder::decodeInteger(childContent, number)) {
        // number holds this member's value
    }
}

Reference generated from certpp/asn1/decoder.hpp at commit 0834b29 (v1.0.1). The header is authoritative --- if this page disagrees with it, the header is right and this page needs regenerating.

Clone this wiki locally