synta 0.2.3

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation
# Quick Reference

Average over 5 PyCA PKITS traditional certificates (914–968 bytes):

| Library           | Parse-only   | Parse+fields | vs synta (parse-only) | vs synta (parse+fields) |
| ----------------- | ------------ | ------------ | --------------------- | ----------------------- |
| **synta**         | **0.48 µs**  | **1.32 µs**  |||
| cryptography-x509 | 1.45 µs      | 1.43 µs      | 3.0× slower           | 1.1× slower             |
| x509-parser       | 2.01 µs      | 1.99 µs      | 4.2× slower           | 1.5× slower             |
| x509-cert         | 3.16 µs      | 3.15 µs      | 6.6× slower           | 2.4× slower             |
| NSS               | 7.90 µs      | 7.99 µs      | 16× slower            | 6.1× slower             |
| rust-openssl      | 15.4 µs      | 15.1 µs      | 32× slower            | 11× slower              |
| ossl              | 16.1 µs      | 15.8 µs      | 33× slower            | 12× slower              |

Parse+fields accesses every named field: serial number, issuer/subject DNs, signature
algorithm OID, signature bytes, validity period, public key algorithm OID, public key bytes,
and version. The parse+fields speedup is the fair end-to-end comparison: synta's parse-only
advantage is large because most fields are stored as zero-copy slices deferred until access,
while other libraries must materialise all fields eagerly at parse time.

## CA Store Throughput

Parse-only, all certs in each dataset:

| Dataset                   | synta              | NSS          | rust-openssl | ossl         |
| ------------------------- | ------------------ | ------------ | ------------ | ------------ |
| Mozilla 181 root CAs      | **90.9 µs** (1.99 M/sec) | 1.58 ms (17×) | 3.55 ms (39×) | 3.62 ms (40×) |
| CCADB 10,036 certs        | **5.06 ms** (1.98 M/sec) | 106 ms (21×) | 203 ms (40×) | 214 ms (42×) |
| ML-DSA synth 9,889 certs  | **5.78 ms** (1.71 M/sec) | 103 ms (18×) | 239 ms (41×) | 256 ms (44×) |

## Recommendations

### When to choose synta

- **Parse-only throughput** (TLS chain checking, CT log scanning, bulk certificate filtering):
  synta is fastest by 3× over the next-best pure-Rust library and 16–33× over C libraries.
- **Parse + all fields**: synta leads all pure-Rust implementations; access is structured
  (named fields, typed return values) rather than offset-based.
- **Post-quantum certificates**: parse time is size-independent — a 7 KB ML-DSA-87 cert
  parses as fast as a 900 B RSA cert due to zero-copy `BitStringRef<'a>` for large payloads.
- **No C dependencies**: all pure Rust; no linking to OpenSSL, NSS, or libtasn1.

**Best practices for maximum performance:**

1. Use typed structures with derive macros (`#[derive(Asn1Sequence)]`) rather than generic
   `Element` — 3.3× faster than equivalent `element_eager` traversal.
2. Use `identify_signature_algorithm()` and `identify_public_key_algorithm()` for OID names
   — returns `&'static str` with no allocation.
3. Use `format_dn()` only when the string representation is actually needed — it allocates.
   Use `issuer_raw()` / `subject_raw()` for byte-level comparison or caching.
4. Use zero-copy types (`BitStringRef<'a>`, `OctetStringRef<'a>`, `RawDer<'a>`) for large
   fields to avoid allocation at parse time.

### When to choose x509-parser

- Need typed access to certificate extensions as an indexed, named collection.
- Need a mature, widely deployed pure-Rust implementation with broad ecosystem adoption.

### When to choose cryptography-x509

- Already using the PyCA `cryptography` Python package and need its full API (signature
  verification, extension parsing, key operations, PEM/DER serialisation).
- Python-first workflow where cryptography ecosystem compatibility matters more than
  parse throughput.