Repository navigation
CDecoder
#include <certpp/asn1/decoder.hpp> --- certpp::asn1
Represents an ASN.1 decoder. This provides static methods for decoding ASN.1 data.
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.
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.
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.
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.
Validates a NULL's content octets.
-
content--- The content octets (must be empty).
Returns: True if content was a valid NULL encoding; otherwise, false.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.