# Codebase Summary
Quick reference for the Synta workspace. For architecture diagrams see
[system-architecture.md](system-architecture.md); for the full developer guide
see the mdbooks under `docs/rust/`, `docs/python/`, `docs/c/`.
---
## Project Metadata
| Name | synta |
| Version | 0.1.7 |
| Language | Rust 2021 + Python 3.8+ |
| License | MIT OR Apache-2.0 |
| Repository | https://codeberg.org/abbra/synta |
| MSRV | Rust stable (current — no minimum pinned) |
---
## Crate Inventory (16 crates)
| `synta` | ~8,000 | Yes | Core DER/BER/CER codec + ASN.1 type system |
| `synta-derive` | ~2,500 | Yes | Proc macros: `Asn1Sequence`, `Asn1Set`, `Asn1Choice` |
| `synta-codegen` | ~5,000 | Yes | ASN.1 schema parser + Rust/C code generator |
| `synta-certificate` | ~18,000 | Yes | X.509, CRL, CSR, OCSP, CMS, PKCS#7/12, builders, OIDs; PKCS#11 URI support: `pkcs11_uri.rs`, `openssl_backend/store.rs`, `nss_backend/hsm_signing.rs`, `nss_backend/rsa_transport.rs`, `nss_backend/ffi.rs`; PKCS#11 token management via `pkcs11-mgmt` feature: `pkcs11_mgmt.rs`, `crypto/token_manager.rs` |
| `synta-cbor` | ~1,500 | Yes | CBOR (RFC 8949) encoder/decoder for all synta ASN.1 types |
| `synta-krb5` | ~3,500 | Yes | Kerberos V5, SPNEGO, GSSAPI, PKINIT ASN.1 types |
| `synta-mtc` | ~4,000 | Yes | Merkle Tree Certificates builder + validator |
| `synta-x509-verification` | ~3,000 | Yes | RFC 5280 certificate path validation (crypto-agnostic) |
| `synta-ffi` | ~4,500 | No | C FFI (`libcsynta`) — opaque handle API |
| `synta-tools` | ~500 | No | CLI utilities (`synta-tool`) |
| `synta-python` | ~8,000 | No | PyO3 extension `_synta.so` |
| `synta-python-common` | ~400 | No | Shared PyO3 helpers (error mapping, OID helpers) |
| `synta-python-krb5` | ~1,200 | No | PyO3 extension `_krb5.so` |
| `synta-python-mtc` | ~800 | No | PyO3 extension `_mtc.so` |
| `synta-bench` | ~3,000 | No | Criterion benchmarks + operational SQLite pipelines |
| `synta-fuzz` | ~400 | No | Structured ASN.1 fuzzer |
---
## File Inventory
| `src/` | Core library: `der/`, `ber/`, `types/`, `traits/`, `tag.rs`, `length.rs`, `error.rs` |
| `synta-derive/src/` | Derive macro impls: `sequence.rs`, `choice.rs`, `set.rs`, `attrs.rs`, `codegen.rs` |
| `synta-codegen/src/` | `parser.rs`, `codegen.rs`, `ast.rs`, `naming.rs`, `c_codegen.rs`, `import_graph.rs` |
| `synta-certificate/src/` | `lib.rs`, `ext_builder.rs` (1,455 lines), `oids.rs` (716 lines), `name.rs`, `pem.rs`, `pubkey.rs`, `pkcs11_uri.rs`, `crypto/`, `openssl_backend/`, `nss_backend/`, `builder.rs`, `csr_builder.rs`, `crl_builder.rs` |
| `synta-certificate/src/openssl_backend/` | `mod.rs`, `private_key.rs`, `store.rs` (OSSL_STORE PKCS#11 key loading), `signature.rs`, `symmetric.rs` |
| `synta-certificate/src/nss_backend/` | `mod.rs`, `ffi.rs` (consolidated NSS FFI declarations), `signing.rs`, `signature.rs`, `hsm_signing.rs` (HSM key loading and signing), `rsa_transport.rs` (RSA-OAEP and PKCS#1 v1.5 via NSS), `symmetric.rs` |
| `synta-certificate/src/crypto/` | `mod.rs`, `private_key.rs`, `utils.rs`, `signature.rs`, `errors.rs`, `key_id.rs` |
| `synta-certificate/tests/` | `pkcs11_kryoptic.rs` (PKCS#11 integration test against a kryoptic token), `openssl_backend_tests.rs`, `nss_backend_tests.rs` |
| `synta-krb5/src/` | `lib.rs`, `constants.rs`, `principal.rs`, `time.rs`, `flags.rs`, `address.rs`, `gss.rs` |
| `synta-mtc/src/` | `types/`, `builder/`, `validator/`, `crypto/`, `config.rs`, `constraint.rs`, `cosignature.rs`, `error.rs`, `integration.rs`, `storage.rs` |
| `synta-x509-verification/src/` | `lib.rs`, `ops.rs`, `types.rs`, `policy/`, `certificate.rs`, `extensions.rs`, `trust_store.rs`, `revocation.rs`, `ocsp.rs` |
| `synta-ffi/src/` | `certificate.rs`, `decoder.rs`, `encoder.rs`, `cms.rs`, `crl.rs`, `csr.rs`, `error.rs`, `types.rs`, `utils.rs` |
| `synta-python/src/` | `lib.rs`, `decoder.rs`, `encoder.rs`, `types/`, `certificate/`, `crypto.rs`, `ext_builders.rs`, `x509_verification.rs`, `crypto_keys.rs` |
| `synta-python/src/certificate/` | `mod.rs`, `pkix.rs`, `general_name.rs`, `cms.rs`, `krb5_ext.rs`, `ac.rs`, `cmp.rs`, `crmf.rs`, `ms_pki.rs`, `pkixalgs.rs` |
| `asn1/` | 47 ASN.1 schema files (X.509, Kerberos, CMS, PKCS, MTC, PQC, ...) |
| `python/synta/` | 19 Python stub modules (`.py` + `.pyi`) |
| `examples/` | 34 Python example scripts |
| `tests/` | Integration tests: `tests/*.rs`, `tests/python/`, `tests/c/`, `tests/vectors/` |
| `synta-bench/benches/` | 14 Criterion benchmark files |
| `docs/` | This documentation tree |
| `contrib/ci/` | `local-ci.sh` (1,293 lines), `README.md`, valgrind suppressions |
| `contrib/packages/` | Fedora/RHEL RPM spec files (8 specs, `Makefile`) |
| `include/` | `synta.h` — auto-generated C header (cbindgen) |
---
## Key Dependencies
### Runtime Dependencies
| `smallvec` | 1.13 | `synta` | Inline storage for `Integer` and `ObjectIdentifier` (avoids heap for common sizes) |
| `ciborium` | 0.2.2 | `synta-cbor` | CBOR encoder/decoder (RFC 8949); `ciborium-ll` for streaming headers; `ciborium-io` for I/O traits |
| `pyo3` | 0.22 | `synta-python*` | Python extension module framework (ABI3 stable API) |
| `maturin` | (build) | `synta-python*` | Build tool for Python extensions |
| `native-ossl` | 0.1.1 | `synta-certificate` | EVP-based OpenSSL 3.x bindings including PQC (ML-DSA, ML-KEM) via build-time cfg flags; used by the `openssl` Cargo feature |
| `cryptoki` | 0.12 | `synta-certificate` | PKCS#11 token management (optional, `dynamic` feature — dlopen at runtime); enabled automatically by the `openssl` or `nss` feature via `pkcs11-mgmt` |
| `log` | 0.4 | `synta-certificate` | Diagnostic logging in the `pkcs11-mgmt` code paths (optional, enabled with `pkcs11-mgmt`) |
| `cbindgen` | (build) | `synta-ffi` | Auto-generates `include/synta.h` from Rust types |
| `cargo-c` | (build) | `synta-ffi` | Builds `libcsynta.so` with pkg-config |
| `serde` | 1 (optional) | `synta`, `synta-mtc` | Serialize/Deserialize support for ASN.1 types |
### Dev / Test Dependencies
| `criterion` | 0.5 | Micro-benchmark framework |
| `rusqlite` | 0.31 | SQLite for operational pipeline benchmarks |
| `rayon` | 1 | Parallel processing in benchmark pipelines |
| `rand` | 0.8 | Random input generation for fuzzer |
| `clap` | 4.5 | CLI argument parsing in tools and fuzzer |
| `ruff` | (Python) | Python linting and formatting |
| `pytest` | 7+ | Python binding test runner |
---
## ASN.1 Schema Coverage (47 files)
| X.509 / PKIX | `X509-Certificate.asn1`, `X509-CRL.asn1`, `PKIX1Explicit-2009.asn1`, `PKIX1Implicit-2009.asn1`, `PKIXAlgs.asn1`, `PKIXAlgs-2009.asn1`, `PKIX-CommonTypes-2009.asn1` |
| Kerberos | `KerberosV5.asn1`, `GssapiSpnego.asn1`, `GssapiKerberos.asn1`, `KerberosFast.asn1`, `KerberosPreauthFramework.asn1`, `KerberosV5AuthenticationIndicators.asn1`, `KerberosV5CAMMAC.asn1`, `OTPKerberos.asn1`, `KerberosV5SPAKE.asn1`, `PKINIT.asn1`, `GSS-API.asn1`, `GSSAPI.asn1` |
| CMS / PKCS#7 | `CMS-RFC5652.asn1`, `CMS-2010.asn1`, `PKCS7-CMS.asn1`, `CMS-KEM.asn1` |
| PKCS standards | `PKCS1.asn1`, `PKCS8.asn1`, `PKCS9.asn1`, `PKCS10-CSR.asn1`, `PKCS5v2-1.asn1`, `PKCS12.asn1` |
| OCSP / TSP | `OCSP.asn1`, `PKIXTSP.asn1` |
| Post-Quantum | `MLDSA.asn1`, `KEMAlgorithmInformation.asn1` |
| Protocols | `ESS.asn1`, `CRMF.asn1`, `CMP.asn1`, `LogotypeCertExtn.asn1`, `AttributeCertificate.asn1`, `ACME-RFC8737.asn1`, `MicrosoftPKI.asn1` |
| MTC | `MTC.asn1` |
| Other | `RFC9925-UnsignedCert.asn1`, `CERT-IMAGE-MODULE.asn1`, `AlgorithmInformation-2009.asn1`, `ACE-88.asn1`, `CborContentTypes.asn1`, `PKIXTestCertPolicies.asn1` |
---
## OID Constants (synta-certificate)
`synta_certificate::oids` exports 200+ OID constants grouped by standard:
| ML-DSA | `ML_DSA_44`, `ML_DSA_65`, `ML_DSA_87` | FIPS 204 |
| ML-KEM | `ML_KEM_512`, `ML_KEM_768`, `ML_KEM_1024` | FIPS 203 |
| SLH-DSA (SHA-2) | `ID_SLH_DSA_SHA2_128S/F`, `*192S/F`, `*256S/F` | FIPS 205 |
| SLH-DSA (SHAKE) | `ID_SLH_DSA_SHAKE_128S/F`, `*192S/F`, `*256S/F` | FIPS 205 |
| EdDSA | `ED25519`, `ED448` | RFC 8410 |
| RSA | `SHA256_WITH_RSA`, `SHA384_WITH_RSA`, `SHA512_WITH_RSA`, `RSASSA_PSS`, `RSAES_OAEP` | PKCS #1 |
| ECDSA | `ECDSA_WITH_SHA256/384/512`, `EC_PUBLIC_KEY` | ANSI X9.62 |
| EC curves | `EC_CURVE_P256`, `EC_CURVE_P384`, `EC_CURVE_P521`, `EC_CURVE_SECP256K1` | SEC 2 |
| Hash (SHA-2) | `ID_SHA224/256/384/512`, `ID_SHA512_224/256` | FIPS 180-4 |
| Hash (SHA-3) | `ID_SHA3_224/256/384/512`, `ID_SHAKE128/256` | FIPS 202 |
| X.509 extensions | `BASIC_CONSTRAINTS`, `KEY_USAGE`, `SUBJECT_ALT_NAME`, `AUTHORITY_KEY_IDENTIFIER`, `NAME_CONSTRAINTS`, etc. | RFC 5280 |
| EKU | `KP_SERVER_AUTH`, `KP_CLIENT_AUTH`, `KP_CODE_SIGNING`, `KP_EMAIL_PROTECTION`, `KP_TIME_STAMPING`, `KP_OCSP_SIGNING` | RFC 5280 §4.2.1.12 |
| DN attributes | `COMMON_NAME`, `ORGANIZATION`, `COUNTRY`, `SERIAL_NUMBER`, etc. | X.500 |
| PKCS#9 | `PKCS9_CONTENT_TYPE`, `PKCS9_MESSAGE_DIGEST`, `PKCS9_SIGNING_TIME`, `PKCS9_EXTENSION_REQUEST` | RFC 2985 |
| Microsoft PKI | `ID_MS_CERTIFICATE_TEMPLATE`, `ID_MS_SAN_UPN`, `ID_MS_KP_SMARTCARD_LOGON` | Microsoft |
| PKINIT | `ID_PKINIT_SAN`, `ID_PKINIT_KPCLIENT_AUTH`, `ID_PKINIT_KPKDC` | RFC 4556 |
---
## Python API Surface
| `synta` | `Encoding`, `Decoder`, `Encoder`, `Certificate`, `CertificationRequest`, `CertificateList`, `OCSPResponse`, `PublicKey`, `PrivateKey`, builders, PEM/DER helpers, `pem_to_der`, `parse_general_names`, `parse_name_attrs`; `PrivateKey` (backed by `BackendPrivateKey`) now supports PKCS#11 URI loading via `from_pkcs11_uri` — see [api-reference.md](api-reference.md#pkcs11-uri-key-loading) |
| `synta.pkcs11` | `SlotInfo`, `KeyInfo`, `Pkcs11Token`, `list_slots`; token management (slot enumeration, key listing, key generation, key deletion) via PKCS#11 — feature-gated (`pkcs11-mgmt`, auto-enabled by `openssl`/`nss`); `None` when feature absent — see [api-reference.md](api-reference.md#python-pkcs11-token-management) |
| `synta.crypto` | `hmac_digest`, `hmac_verify`, `pbkdf2_hmac`, `hkdf_extract`, `hkdf_expand`, `HmacDigest` (streaming), AES-CBC encrypt/decrypt, Triple-DES CBC encrypt/decrypt, `pkcs7_pad/unpad`, `Fernet`, `HOTP`, `TOTP` |
| `synta.ext` | Extension value builders: `basic_constraints`, `key_usage`, `SubjectAlternativeNameBuilder`, `NameConstraintsBuilder`, etc. |
| `synta.x509` | `TrustStore` (pre-parses + caches trust anchors via `OwnedStore`), `CrlStore`, `OcspStore`, `VerificationPolicy`, `verify_server_certificate`, `verify_client_certificate` |
| `synta.cms` | `ContentInfo`, `SignedData`, `SignerInfo`, `EnvelopedData`, `EnvelopedDataBuilder` |
| `synta.krb5` | `Krb5PrincipalName`, `UPN`, `NT_*` constants, `ETYPE_*` constants |
| `synta.spnego` | `NegTokenInit`, `NegTokenResp`, `NegotiationToken`, `NegState.*` |
| `synta.general_name` | `DNSName`, `IPAddress`, `Rfc822Name`, `Uri`, `DirectoryName`, `OtherName` |
| `synta.oids` | 500+ OID constants for algorithms, attributes, extensions |
| `synta.oids.attr` | X.500 DN attribute OIDs (`cn`, `o`, `ou`, `c`, `uid`, `mail`, ...) |
| `synta.mtc` | Merkle Tree Certificate types |
| `synta.ac` | Attribute Certificates (RFC 5755) |
| `synta.cms` | CMS SignedData, EnvelopedData, and related OID constants |
---
## Test Coverage
| Core DER/BER unit tests | `tests/*.rs` | Decoder, encoder, all ASN.1 types, tag/length, roundtrip, serde |
| Certificate tests | `synta-certificate/tests/` | X.509 parsing with pyca/cryptography test vectors, PKCS#11 HSM integration (`pkcs11_kryoptic.rs`) |
| Codegen tests | `synta-codegen/tests/` | ASN.1 schema parsing and Rust code generation |
| Kerberos tests | `synta-krb5/tests/` | Kerberos V5 ASN.1 structures |
| MTC tests | `synta-mtc/tests/` | Merkle Tree Certificate validation + property tests |
| x509-limbo | `synta-x509-verification/tests/limbo/` | RFC 5280 compliance (~39 MB x509-limbo test suite) |
| Python binding tests | `tests/python/` | All Python API surface via pytest |
| C FFI tests | `tests/c/` | C API bindings via make |
---
## CI Jobs Summary (26 total)
| Build | `build` (debug + release + cbuild) |
| Lint | `fmt`, `clippy`, `ruff`, `toc`, `lint-workflows` |
| Documentation | `doc`, `doc-c`, `doc-rust`, `doc-python` |
| Tests | `test` (stable/beta/nightly), `c-test`, `python-test`, `test-codegen`, `test-certificate`, `test-krb5`, `test-mtc`, `test-limbo`, `test-serde` |
| Benchmarks | `bench`, `bench-compare`, `bench-bindings`, `bench-ca-roots` |
| Security | `fuzz` |
Run locally: `./contrib/ci/local-ci.sh all`
---
## See Also
- [System Architecture](system-architecture.md) — crate dependency graphs, data flow, memory model
- [Limitations](limitations.md) — unsupported ASN.1 constructs in `synta-codegen`
- [Post-Quantum OIDs](POST_QUANTUM_OIDS.md) — ML-DSA, ML-KEM, SLH-DSA OID reference
- [Contributing](contribution.md) — development setup, CI, commit conventions
- [API Reference](api-reference.md) — generated rustdoc (build with `cargo doc --open`)