#ASN.1 DER

#define FIO_DER
#include "fio-stl.h"

ASN.1 DER is the small binary grammar hiding inside X.509 certificates, keys, signatures, and TLS messages. This module parses and writes the pieces facil.io needs for that world.

The parser is non-allocating. Parsed elements point into the original DER buffer, so keep that buffer alive while you use the results. No buffer, no treasure map.

#Core Types

#`fio_der_element_s`

typedef struct {
  const uint8_t *data;
  size_t len;
  uint8_t tag;
  uint8_t is_constructed;
  uint8_t tag_class;
  uint8_t tag_number;
} fio_der_element_s;

A parsed DER element. data points to the content bytes, after the tag and length fields. len is the content length. The remaining fields describe the tag byte.

#`fio_der_iterator_s`

typedef struct {
  const uint8_t *pos;
  const uint8_t *end;
} fio_der_iterator_s;

Iterator state for walking a SEQUENCE or SET element.

#Tags and Classes

fio_der_tag_e defines the common universal tags, including FIO_DER_INTEGER, FIO_DER_BIT_STRING, FIO_DER_OID, FIO_DER_SEQUENCE, FIO_DER_SET, string types, FIO_DER_UTC_TIME, FIO_DER_GENERALIZED_TIME, and context wrappers FIO_DER_CONTEXT_0 through FIO_DER_CONTEXT_3.

fio_der_class_e names the tag classes: universal, application, context-specific, and private.

#OID Values

OID constants live in the X.509 module (FIO_X509_OID_*, see the X.509 documentation). An OID value is a plain fio_u128 where bytes 0-14 hold the DER content bytes (zero-padded) and byte 15 holds the content length. The length is folded in because 0x00 is a legal OID content byte (arc 0), so padding alone could not distinguish {..0B} from {..0B 00} - different OIDs. Oversized OIDs (content > 15 bytes) simply never match, which is safe: AlgorithmIdentifier OIDs are attacker-controlled and RFC 5280 requires exact match.

Build a value once per parsed element with fio___der_oid_value (internal), then compare it against any number of constants with fio___der_oid_eq (internal) - two u64-lane == comparisons, no memcmp, no call:

fio_u128 oid = fio___der_oid_value(&elem); /* build ONCE per element */
if (fio___der_oid_eq(oid, FIO_X509_OID_COMMON_NAME)) { /* ... */ }

#Parsing

#`fio_der_parse`

SFUNC const uint8_t *fio_der_parse(fio_der_element_s *elem,
                                    const uint8_t *data,
                                    size_t data_len);

Parses one DER element. On success, fills elem and returns a pointer to the next element. On error, returns NULL.

It rejects invalid DER lengths, truncated buffers, unsupported high-tag-number encodings, and indefinite lengths.

#`fio_der_element_total_len`

FIO_IFUNC size_t fio_der_element_total_len(const fio_der_element_s *elem,
                                            const uint8_t *data);

Returns the full encoded length of an element: tag + length + content. data must be the original pointer used to parse the element.

#Type Parsers

#`fio_der_parse_integer`

SFUNC int fio_der_parse_integer(const fio_der_element_s *elem,
                                 uint64_t *value);

Parses an ASN.1 INTEGER. For small integers, pass value and receive the 64-bit value. For large integers such as RSA moduli, pass NULL and use elem->data / elem->len directly. Leading zero bytes for positive integers are handled.

Returns 0 on success, -1 on error.

#`fio_der_parse_bit_string`

SFUNC int fio_der_parse_bit_string(const fio_der_element_s *elem,
                                    const uint8_t **bits,
                                    size_t *bit_len,
                                    uint8_t *unused_bits);

Parses an ASN.1 BIT STRING. bits points into the element data after the unused-bit count byte. bit_len is the byte length of the bit payload. unused_bits is the number of unused bits in the last byte.

#`fio_der_parse_oid`

SFUNC int fio_der_parse_oid(const fio_der_element_s *elem,
                             char *buf,
                             size_t buf_len);

Converts an ASN.1 OBJECT IDENTIFIER into dotted text such as 1.2.840.113549.1.1.11.

Returns the number of characters written, excluding the NUL byte, or -1 on error.

#`fio_der_parse_time`

SFUNC int fio_der_parse_time(const fio_der_element_s *elem,
                              int64_t *unix_time);

Parses UTCTime or GeneralizedTime into a Unix timestamp. Times must be UTC (Z). Fractional seconds are skipped when present.

#`fio_der_parse_string`

FIO_IFUNC const char *fio_der_parse_string(const fio_der_element_s *elem,
                                            size_t *len);

Returns a pointer to the string bytes for supported ASN.1 string tags, with the byte length in len. This does not validate or transcode the text; it simply gives you the payload.

#`fio_der_parse_boolean`

FIO_IFUNC int fio_der_parse_boolean(const fio_der_element_s *elem,
                                     int *value);

Parses a DER boolean and writes 0 or non-zero to value.

#Walking Sequences and Sets

#`fio_der_iterator_init`

FIO_IFUNC void fio_der_iterator_init(fio_der_iterator_s *it,
                                      const fio_der_element_s *sequence);

Initializes an iterator over the content bytes of a parsed SEQUENCE or SET.

#`fio_der_iterator_next`

SFUNC int fio_der_iterator_next(fio_der_iterator_s *it,
                                 fio_der_element_s *elem);

Parses the next child element and advances the iterator. Returns 0 when an element was read, -1 at end or on parse error.

#`fio_der_iterator_has_next`

FIO_IFUNC int fio_der_iterator_has_next(const fio_der_iterator_s *it);

Returns 1 when the iterator still has bytes to parse, otherwise 0.

#Tag Helpers

FIO_IFUNC int fio_der_is_tag(const fio_der_element_s *elem, uint8_t tag);
FIO_IFUNC int fio_der_is_context_tag(const fio_der_element_s *elem,
                                      uint8_t tag_num);
FIO_IFUNC uint8_t fio_der_tag_number(const fio_der_element_s *elem);

Use these to keep parser code readable:

fio_der_is_tag checks a universal tag such as FIO_DER_INTEGER.
fio_der_is_context_tag checks [0], [1], and friends.
fio_der_tag_number returns the decoded tag number.

#Encoding

All encoder functions return the number of bytes written or needed. Pass NULL as buf to calculate the encoded length before writing.

#Basic Encoders

SFUNC size_t fio_der_encode_length(uint8_t *buf, size_t len);
SFUNC size_t fio_der_encode_integer(uint8_t *buf,
                                     const uint8_t *data,
                                     size_t data_len);
SFUNC size_t fio_der_encode_integer_small(uint8_t *buf, uint64_t value);
SFUNC size_t fio_der_encode_null(uint8_t *buf);
SFUNC size_t fio_der_encode_boolean(uint8_t *buf, int value);

These write DER length fields, positive integers, NULL, and booleans. fio_der_encode_integer expects big-endian integer bytes and adds the leading zero byte when DER needs one to keep the integer positive.

OIDs are encoded with the internal fio___der_encode_oid(buf, fio_u128 oid), which TLV-wraps an OID value (see OID Values above) without any dot-string parsing.

#String and Byte Encoders

SFUNC size_t fio_der_encode_utf8_string(uint8_t *buf,
                                         const char *str,
                                         size_t str_len);
SFUNC size_t fio_der_encode_printable_string(uint8_t *buf,
                                              const char *str,
                                              size_t str_len);
SFUNC size_t fio_der_encode_bit_string(uint8_t *buf,
                                        const uint8_t *bits,
                                        size_t bit_len,
                                        uint8_t unused_bits);
SFUNC size_t fio_der_encode_octet_string(uint8_t *buf,
                                          const uint8_t *data,
                                          size_t data_len);

These write the tag, DER length, and payload for common primitive values.

#Header Encoders

SFUNC size_t fio_der_encode_sequence_header(uint8_t *buf, size_t content_len);
SFUNC size_t fio_der_encode_set_header(uint8_t *buf, size_t content_len);
SFUNC size_t fio_der_encode_context_header(uint8_t *buf,
                                            uint8_t tag_num,
                                            size_t content_len,
                                            int constructed);

These write only the wrapper tag and length. Write the content bytes immediately after the returned header length.

#Time Encoders

SFUNC size_t fio_der_encode_utc_time(uint8_t *buf, int64_t unix_time);
SFUNC size_t fio_der_encode_generalized_time(uint8_t *buf, int64_t unix_time);

These encode Unix timestamps as DER UTCTime or GeneralizedTime.

#Example

#define FIO_DER
#include "fio-stl.h"

void scan_sequence(const uint8_t *der, size_t der_len) {
  fio_der_element_s seq;
  if (!fio_der_parse(&seq, der, der_len))
    return;
  if (!fio_der_is_tag(&seq, FIO_DER_SEQUENCE))
    return;

  fio_der_iterator_s it;
  fio_der_iterator_init(&it, &seq);

  fio_der_element_s elem;
  while (fio_der_iterator_next(&it, &elem) == 0) {
    if (fio_der_is_tag(&elem, FIO_DER_OID)) {
      fio_u128 oid = fio___der_oid_value(&elem);
      /* compare with FIO_X509_OID_* constants via fio___der_oid_eq, or */
      char dot[128];
      if (fio_der_parse_oid(&elem, dot, sizeof(dot)) > 0) {
        /* dotted string available for diagnostics */
      }
    }
  }
}

#ASN.1 DER

#Core Types

#fio_der_element_s

#fio_der_iterator_s

#Tags and Classes

#OID Values

#Parsing

#fio_der_parse

#fio_der_element_total_len