# Synta Python Bindings
Synta is a high-performance Rust ASN.1 library. This book documents its Python
bindings — native extension modules built with [PyO3](https://pyo3.rs/) and
[maturin](https://www.maturin.rs/).
## What the bindings provide
The `synta` Python package exposes Rust types directly to Python, providing
near-native performance while preserving Python's ease of use:
- **Core ASN.1 codec** — `Decoder`, `Encoder`, all primitive types
(`Integer`, `OctetString`, `ObjectIdentifier`, `BitString`, `Boolean`,
`Real`, `Null`, string types, time types, `TaggedElement`, `RawElement`).
- **X.509 PKI** — parse `Certificate`, `CertificationRequest`,
`CertificateList`, and `OCSPResponse`; extract bundles from PKCS#7 and
PKCS#12 archives; build CRLs and OCSP responses; verify certificate chains;
encode X.509 extension values.
- **CMS cryptography** — full RFC 5652 and RFC 9629 type coverage:
`ContentInfo`, `SignedData`/`SignerInfo`, `EnvelopedData`, `EncryptedData`,
`DigestedData`, `AuthenticatedData`, and CMS-KEM types.
- **Protocol schemas** — Kerberos V5 and PKINIT (`synta.krb5`), SPNEGO
(`synta.spnego`), RFC 3279 algorithm parameters (`synta.pkixalgs`),
Attribute Certificates (`synta.ac`), CRMF (`synta.crmf`), CMP (`synta.cmp`),
PKCS#8 (`synta.pkcs8`), Microsoft PKI extensions (`synta.ms_pki`), and
Merkle Tree Certificates (`synta.mtc`).
- **OID constants** — 70+ well-known OIDs and helper functions in `synta.oids`
- **Schema decorators** — `synta.schema` provides `@asn1_sequence`, `@asn1_choice`, and
`asn1_field()` for defining ASN.1 SEQUENCE and CHOICE types directly in Python using
class decorators and type annotations, with automatic `to_der()` and `from_der()` support.
and `synta.oids.attr`.
## Implementation notes
The package is implemented as three native extension modules that are loaded
automatically when you do `import synta`:
| `_synta.abi3.so` | maturin (`synta-python` crate) | `synta`, `synta-certificate`, `synta-x509-verification` |
| `_krb5.abi3.so` | cargo (`synta-python-krb5` crate) | `synta-krb5` — registers `synta.krb5` and `synta.spnego` |
| `_mtc.abi3.so` | cargo (`synta-python-mtc` crate) | `synta-mtc` — registers `synta.mtc` |
`synta.ObjectIdentifier` and `synta.SyntaError` are defined in `_synta.so` only.
The subsystem modules look them up from `sys.modules["synta._synta"]` at init
time, so `isinstance(oid, synta.ObjectIdentifier)` returns `True` for OID values
produced by any of the three modules.
`synta-python-common` is an rlib (no Python module) statically linked into all
three cdylibs; it provides shared error-bridging and submodule-registration code.
## How to navigate this book
- **[Installation and Building](getting-started/installation.md)** — build from source and install.
- **[Quick Start](getting-started/quickstart.md)** — minimal decode and encode examples to get started.
- **[Module Layout](getting-started/module-layout.md)** — the full `synta` module tree and extension module architecture.
- **[Core ASN.1 Codec](core/encoding-rules.md)** — `Decoder`, `Encoder`, primitive types, `ObjectIdentifier`, and error handling.
- **[X.509 PKI](pki/pem-der.md)** — parse certificates, CSRs, CRLs, and OCSP responses; read PKCS#7 and PKCS#12 archives; build and verify certificate chains.
- **[CMS Cryptography](cms/overview.md)** — RFC 5652 signed, enveloped, encrypted, and authenticated data; CMS-KEM.
- **[Protocol Schemas](protocols/krb5.md)** — ASN.1 schemas for network protocols: Kerberos V5, SPNEGO, CRMF, CMP, TSP, ESS, PKCS#8, and more.
- **[Merkle Tree Certificates](protocols/mtc.md)** — `synta.mtc`: draft MTC parsing and trust-anchor verification.
- **[OID Reference](oids/oids.md)** — well-known OID constants grouped by namespace.
- **[Schema Decorators](core/schema.md)** — `synta.schema`: define ASN.1 SEQUENCE and CHOICE types in Python with automatic DER encode/decode.
- **[Performance and Development](dev/performance.md)** — benchmarks, project structure, and Cargo features.
- **[Example Programs](examples/index.md)** — 32 runnable examples covering every binding.
For the Rust API, code-generation tutorial, and ASN.1 schema authoring see
the [Rust API book](../../rust/src/getting-started/installation.md).