synta 0.1.2

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

# 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)
- [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

- **Typed parsing** — derive macros (`Asn1Sequence`, `Asn1Choice`, `Asn1Set`) generate
  compile-time-specialised decoders with negligible overhead versus manual implementation
- **Zero-copy** — `BitStringRef<'a>`, `OctetStringRef<'a>`, `RawDer<'a>` borrow directly
  from the input buffer; no allocation for large fields such as DN byte spans or signatures
- **DER, BER, CER** — full encoding rules support
- **Code generation** — `synta-codegen` 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 zero-copy `RawDer` output for open-typed (`ANY`) fields
- **C/C++ FFI** — 100+ function C API (`synta-ffi` crate) for certificates, CRLs, CSRs,
  OCSP, PEM, PKCS#7/12, and full CMS (RFC 5652): `ContentInfo`, `SignedData`, `EnvelopedData`,
  `EncryptedData` (encrypt/decrypt with AES-CBC via `openssl` feature), `DigestedData`;
  header at `include/synta.h`
- **Python bindings** — PyO3-based, Python 3.8+ stable ABI (`synta-python` crate); exposes
  `Certificate`, `CertificationRequest`, `CertificateList`, `OCSPResponse`, a `synta.cms`
  submodule with `EncryptedData.create`/`decrypt` (AES-CBC, `openssl` feature),
  `parse_general_names`, `parse_name_attrs`, `load_pkcs12_keys`, `Decoder.decode_any_str`,
  `synta.general_name` tag constants, and PKCS#9 attribute OID constants
- **X.509 PKI suite** — certificates, CRLs (RFC 5280), CSRs (RFC 2986), OCSP (RFC 6960),
  full CMS (RFC 5652: SignedData, EnvelopedData, EncryptedData, DigestedData, KEM recipient
  info), PKCS#8 (RFC 5958), PKCS#9 OID constants (RFC 2985), PKCS#12 certificate and
  private-key extraction (RFC 7292), Subject Alternative Name parsing, DN attribute parsing,
  pure-Rust PEM (RFC 7468) in `synta-certificate`
- **Kerberos V5** — RFC 4120/4121/4178/6113 types in `synta-krb5`; all 15 `ETYPE_*`
  encryption-type constants exposed to Python (`synta.krb5`)
- **no_std** — core functionality works in embedded environments (see [docs/no_std.md](docs/no_std.md))
- **Serde** — optional JSON/CBOR/MessagePack serialization (`features = ["serde"]`)

## 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 quick reference | [docs/PYTHON_BINDINGS.md](docs/PYTHON_BINDINGS.md) |
| Python bindings complete catalog | [docs/python-bindings-guide.md](docs/python-bindings-guide.md) |
| Kerberos V5 types | [synta-krb5/README.md](synta-krb5/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).