synta 0.2.6

ASN.1 parser, decoder, and encoder library with DER/BER support and C FFI
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203

# Synta

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Features](#features)
  - [Core ASN.1 codec](#core-asn1-codec)
  - [Code generation ([synta-codegen](synta-codegen/README.md))](#code-generation-synta-codegen)
  - [X.509 PKI ([synta-certificate](synta-certificate/README.md#features))](#x509-pki-synta-certificate)
  - [CBOR codec ([synta-cbor](synta-cbor/))](#cbor-codec-synta-cbor)
  - [Protocol schemas](#protocol-schemas)
  - [X.509 path validation ([synta-x509-verification](synta-x509-verification/README.md))](#x509-path-validation-synta-x509-verification)
  - [Language bindings](#language-bindings)
- [Documentation](#documentation)
- [Testing](#testing)
- [Performance](#performance)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

High-performance Rust library for ASN.1 parsing, encoding, and decoding.

**~0.48 µs** per X.509 certificate parse-only — 3.1× faster than the next-best
pure-Rust implementation, 18× faster than NSS. See [docs/performance.md](docs/performance.md).

## Installation

```toml
[dependencies]
synta = "0.1"

# With serde Serialize/Deserialize support
synta = { version = "0.1", features = ["serde"] }

# no_std with alloc
synta = { version = "0.1", default-features = false, features = ["alloc"] }
```

## Quick Start

Decode and encode a primitive type:

```rust
use synta::{Decoder, Encoder, Encoding, Integer};

let data = &[0x02, 0x01, 0x2A]; // DER INTEGER 42
let mut decoder = Decoder::new(data, Encoding::Der);
let value: Integer = decoder.decode().unwrap();
assert_eq!(value.as_i64().unwrap(), 42);

let mut encoder = Encoder::new(Encoding::Der);
encoder.encode(&value).unwrap();
assert_eq!(encoder.finish().unwrap(), data);
```

Typed parsing with derive macros — the recommended approach for production use:

```rust,ignore
use synta::{Decoder, Encoding, Integer, ObjectIdentifier};
use synta_derive::Asn1Sequence;

#[derive(Asn1Sequence)]
struct AlgorithmIdentifier {
    pub algorithm: ObjectIdentifier,
    #[asn1(optional)]
    pub parameters: Option<Integer>,
}

let mut decoder = Decoder::new(der_bytes, Encoding::Der);
let alg: AlgorithmIdentifier = decoder.decode()?;
```

Typed decoding generates compile-time-specialised, inlined decode paths and is
3.3× faster than equivalent generic `Element` traversal.

See [docs/tutorial.md](docs/tutorial.md) for a step-by-step introduction and
[docs/usage.md](docs/usage.md) for the full API guide.

## Features

### Core ASN.1 codec

- **Typed parsing** — `Asn1Sequence`, `Asn1Choice`, `Asn1Set` derive macros generate compile-time-specialised decoders; 3.3× faster than generic `Element` traversal
- **Zero-copy** — `RawDer<'a>`, `OctetStringRef<'a>`, `BitStringRef<'a>` borrow from the input buffer with no allocation for large fields
- **Encoding rules** — DER, BER, and CER all supported
- **no_std** — core functionality works in embedded environments with the `alloc` feature; see [docs/no_std.md](docs/no_std.md)
- **Serde** — optional `Serialize`/`Deserialize` via `features = ["serde"]`

### Code generation ([synta-codegen](synta-codegen/README.md))

- Compiles ASN.1 schema files to ready-to-use Rust or C structs
- Supports ASN.1 Information Object Class parsing, configurable derive-macro gating (`DeriveMode`), and `RawDer` output for `ANY` fields

### X.509 PKI ([synta-certificate](synta-certificate/README.md#features))

- **Parsing** — X.509 v3 certificates, CRLs (RFC 5280), CSRs (RFC 2986), OCSP responses (RFC 6960)
- **Builders** — `CertificateBuilder`, `CsrBuilder`, `Pkcs12Builder`, `CertificateListBuilder`, `OCSPResponseBuilder`, `AttributeCertificateBuilder`, `CertReqMsgBuilder`, `CMPMessageBuilder` with pluggable signer and encryptor traits; `OpensslCertificateSigner` and `OpensslPkcs12Encryptor` backends
- **Bundle formats** — PKCS#7 SignedData certificate extraction; PKCS#12 certificate/private-key extraction and creation
- **CMS full suite** — `SignedData`, `EnvelopedData` (one-call `create_enveloped_data` or two-step `prepare_enveloped_data` + builder for originator info), `EncryptedData` (AES-CBC encrypt/decrypt), `DigestedData`, KEM recipient info; requires `openssl` feature for crypto
- **Post-quantum** — standalone ML-DSA-44/65/87 (FIPS 204) and 18 composite ML-DSA algorithms (draft-ietf-lamps-pq-composite-sigs-19, OID sub-arcs 37–54) combining ML-DSA with RSA/ECDSA/EdDSA; `PrivateKeyBuilder::composite_ml_dsa(sub_arc)` for backend-agnostic key generation; requires `openssl` + `pqc` (OpenSSL 3.3+) or `nss` feature
- **Schema types** — RFC 3279 algorithm parameters, Attribute Certificates (RFC 5755), CRMF (RFC 4211), CMP v3 (RFC 9810)
- **Helpers** — DN formatting and attribute parsing, SAN parsing, zero-alloc algorithm identification, PEM encode/decode

### CBOR codec ([synta-cbor](synta-cbor/))

- `CborEncode` / `CborDecode` traits — CBOR-specific codec API, separate from the DER/BER `Encode`/`Decode` traits
- `CborEncoder` / `CborDecoder` — streaming wrappers over `ciborium_ll` for writing and reading CBOR headers and bodies
- `ToCbor` / `FromCbor` — blanket convenience traits (like `ToDer` / `FromDer`) that serialise to / from `Vec<u8>`
- Full type coverage: all ASN.1 primitives, string types, time types, constructed types, `ObjectIdentifier` (RFC 9090 tag 111), tagged types
- Optional `certificate` feature: `unwrap_cms_cbor` CMS helper requires `synta-certificate`

### Protocol schemas

- **Kerberos V5** — RFC 4120/4121/4178/6113 types; typed flag wrappers for `KDCOptions`, `TicketFlags`, `APOptions`; principal, time, address, and GSS token helpers ([synta-krb5](synta-krb5/README.md#features))
- **Merkle Tree Certificates** — draft-ietf-plants-merkle-tree-certs issuance log builder, inclusion proof generation and verification, trust anchor management with cosignature support ([synta-mtc](synta-mtc/README.md))

### X.509 path validation ([synta-x509-verification](synta-x509-verification/README.md))

- RFC 5280 §6 + CABF Baseline Requirements chain verification
- Crypto-agnostic via `SignatureVerifier` plug-in trait; OpenSSL backend available
- Name constraint enforcement (DNS, IP, RFC 822 email)
- Configurable extension policy and trust store
- OCSP revocation checking via `OcspStore`
- Python bindings in `synta.x509` (`TrustStore`, `VerificationPolicy`, `verify_server_certificate`, `verify_client_certificate`)

### Language bindings

**C/C++ FFI** ([synta-ffi](synta-ffi/README.md#cargo-features)) — 100+ exported functions covering:
- ASN.1 primitives, string types, time types, constructed types, OIDs
- X.509 certificates, CRLs (RFC 5280), PKCS#10 CSRs, OCSP responses (RFC 6960)
- PEM encode/decode; PKCS#7 and PKCS#12 certificate extraction
- Full CMS: `ContentInfo`, `SignedData`, `EnvelopedData`, `EncryptedData` (AES-CBC, `openssl` feature), `DigestedData`
- Header auto-generated at `include/synta.h` by cbindgen

**Python** ([synta-python](synta-python/README.md#cargo-features)) — PyO3-based, Python 3.8+ stable ABI:
- `Certificate`, `CertificationRequest`, `CertificateList`, `OCSPResponse`, `PublicKey`, `PrivateKey` (with ML-DSA/ML-KEM key generation, sign, verify, KEM encapsulate/decapsulate; composite ML-DSA OIDs recognized for parsing/verification)
- Builders: `CertificateBuilder`, `CsrBuilder`, `CertificateListBuilder`, `OCSPResponseBuilder`, `AttributeCertificateBuilder`, `CertReqMsgBuilder`/`CertReqMessagesBuilder`, `CMPMessageBuilder`; PKCS#12: `load_pkcs12_*`, `create_pkcs12`
- `synta.cms` — full CMS suite: `ContentInfo`, `SignedData`, `EnvelopedData`, `EnvelopedDataBuilder`, `EncryptedData`, `DigestedData`, KEM recipient info
- `synta.kem` — KEM recipient info types (`KEMRecipientInfo`, `CMSORIforKEMOtherInfo`) and ML-KEM OID constants (RFC 9629)
- `synta.pkcs8` — PKCS #8 / RFC 5958 private key parsing (`OneAsymmetricKey` / `PrivateKeyInfo`)
- `synta.pkcs9` — PKCS #9 attribute OID constants (13 OIDs from RFC 2985 / RFC 5652)
- `synta.x509` — RFC 5280 / CABF chain verification; `synta.krb5` — Kerberos V5 / PKINIT types
- `synta.oids` — well-known OID constants and algorithm identification helpers

## Documentation

| Topic | Location |
|-------|----------|
| Tutorial (step-by-step) | [docs/tutorial.md](docs/tutorial.md) |
| Usage guide — typing, sequences, serde, config | [docs/usage.md](docs/usage.md) |
| Codegen CLI and library API reference | [docs/api-reference.md](docs/api-reference.md) |
| Rust code generation from ASN.1 schemas | [docs/rust-generation.md](docs/rust-generation.md), [synta-codegen/README.md](synta-codegen/README.md) |
| C code generation from ASN.1 schemas | [docs/c-generation.md](docs/c-generation.md) |
| Supported ASN.1 syntax | [docs/asn1-support.md](docs/asn1-support.md) |
| C/C++ FFI reference | [docs/C_API.md](docs/C_API.md), [docs/C_MEMORY.md](docs/C_MEMORY.md) |
| Python bindings documentation | [docs/python/src/introduction.md](docs/python/src/introduction.md) |
| Kerberos V5 types | [synta-krb5/README.md](synta-krb5/README.md) |
| X.509 path validation | [synta-x509-verification/README.md](synta-x509-verification/README.md) |
| Performance benchmarks | [docs/performance.md](docs/performance.md) |
| Best practices | [docs/best-practices.md](docs/best-practices.md) |
| no_std environments | [docs/no_std.md](docs/no_std.md) |
| Migration from OpenSSL | [docs/MIGRATION_OPENSSL.md](docs/MIGRATION_OPENSSL.md) |
| Migration from libtasn1 | [docs/MIGRATION_LIBTASN1.md](docs/MIGRATION_LIBTASN1.md) |
| Contributing | [docs/contribution.md](docs/contribution.md) |
| CI reference | [contrib/ci/README.md](contrib/ci/README.md) |

## Testing

```bash
cargo test                             # core library
cargo test --workspace --all-features  # full workspace

# Full CI pipeline: fmt, clippy, doc, C tests, Python tests, benchmarks
./contrib/ci/local-ci.sh all
./contrib/ci/local-ci.sh clippy        # individual job
./contrib/ci/local-ci.sh --valgrind c-test test
```

See [contrib/ci/README.md](contrib/ci/README.md) for all available jobs and flags.

## Performance

X.509 certificate parsing (traditional RSA/ECDSA, avg of 5 certs):

| Library | Parse-only | Parse + all fields |
|---------|-----------|-------------------|
| **synta** | **0.48 µs** | **1.38 µs** |
| cryptography-x509 | 1.51 µs | 1.51 µs |
| x509-parser | 2.13 µs | 2.11 µs |
| x509-cert | 3.33 µs | 3.36 µs |
| NSS | 8.46 µs | 8.50 µs |

Parse time is **size-independent**: 7 KB post-quantum ML-DSA certificates parse as fast
as 900 B traditional ones. Full data including post-quantum, CA store throughput, and
methodology: [docs/performance.md](docs/performance.md).

## License

Apache-2.0 or MIT, at your option.
See [LICENSE-APACHE](LICENSE-APACHE) and [LICENSE-MIT](LICENSE-MIT).