# PyCA Interoperability
`synta.Certificate` and `cryptography.x509.Certificate` can be converted back and forth.
The two libraries are complementary and can coexist in the same process; the conversion
is designed for environments where both are already in use and you need to hand certificate
objects between them without re-parsing.
synta provides its own full cryptographic operation support — signature verification,
key generation and signing, asymmetric encryption, and KEM operations — through its
[`PublicKey` and `PrivateKey`](keys.md) API. PyCA interop is **not** needed to do
cryptography; it is for transparent data handover when both libraries are present.
Requires the [`cryptography`](https://cryptography.io) package (`pip install cryptography`).
Both methods raise `ImportError` with an actionable message if the package is absent.
## When to use each library
| Parsing certificates at scale | synta (4–10× faster, lazy decode) |
| Accessing certificate fields | synta (cached, zero-copy getters) |
| Signature verification | synta `Certificate.verify_issued_by()` or `PublicKey.verify_signature()` |
| Key generation and signing | synta `PrivateKey.generate_*()` / `PrivateKey.sign()` |
| Asymmetric encryption / decryption | synta `PublicKey.rsa_oaep_encrypt()` / `PrivateKey.rsa_oaep_decrypt()` |
| KEM encapsulate / decapsulate | synta `PublicKey.kem_encapsulate()` / `PrivateKey.kem_decapsulate()` |
| Integrating with an existing PyCA code path | `cert.to_pyca()` / `Certificate.from_pyca()` |
| Receiving a `cryptography.x509.Certificate` from a third-party library | `Certificate.from_pyca()` |
## Conversion methods
```text
cert.to_pyca() -> cryptography.x509.Certificate
```
Return a `cryptography.x509.Certificate` backed by the same DER bytes.
No re-encoding occurs; the original DER buffer is passed directly to
`load_der_x509_certificate`. Use this to hand a synta-parsed certificate to a
function or library that expects a PyCA object.
```text
Certificate.from_pyca(pyca_cert: object) -> Certificate
```
Convert a `cryptography.x509.Certificate` to a `synta.Certificate`. Checks
`obj._synta_der_bytes` first (the fast path when the object was originally created by
synta's `to_pyca()`); falls back to `public_bytes(Encoding.DER)` otherwise.
Use this when you receive a PyCA certificate from a third-party library and want
synta's fast field access or bulk-processing capabilities.
## Usage
### Handing a synta certificate to a PyCA-based API
```python
import synta
synta_cert = synta.Certificate.from_der(open("cert.der", "rb").read())
# Fast field access via synta (cached after first call):
print(synta_cert.subject)
print(synta_cert.not_before, "–", synta_cert.not_after)
# Hand off to a third-party function that requires a PyCA certificate:
pyca_cert = synta_cert.to_pyca()
some_pyca_library.register_certificate(pyca_cert)
```
### Verifying a certificate chain using synta's own verifier
```python
import synta
import synta.x509 as x509
# synta has full chain verification — no PyCA needed.
cert_der = open("cert.der", "rb").read()
# TrustStore takes a list of DER bytes; use pem_to_der to load a PEM bundle.
ca_ders = synta.pem_to_der(open("ca.pem", "rb").read())
store = x509.TrustStore(ca_ders)
# server_names is a list; intermediates_der is [] when the chain is not split.
policy = x509.VerificationPolicy(server_names=["example.com"])
chain = x509.verify_server_certificate(cert_der, [], store, policy)
print("chain valid:", [synta.Certificate.from_der(d).subject for d in chain])
```
### Receiving a PyCA certificate from a third-party library
```python
import synta
from cryptography.x509 import load_pem_x509_certificate
# Some external library hands you a PyCA certificate.
pyca_cert = load_pem_x509_certificate(open("cert.pem", "rb").read())
# Convert to synta for fast bulk field access.
synta_cert = synta.Certificate.from_pyca(pyca_cert)
print(hex(synta_cert.serial_number))
print(synta_cert.subject_alt_names())
```
### Signing a CSR with synta's own key API
```python
import synta
from synta import CsrBuilder
# Generate key and sign a CSR entirely within synta — no PyCA required.
key = synta.PrivateKey.generate_ec("P-256")
csr_der = (
CsrBuilder()
.subject_common_name("example.com")
.add_san_dns("example.com")
.build(key)
)
csr = synta.CertificationRequest.from_der(csr_der)
csr.verify_self_signature() # verify the CSR's proof-of-possession
```
## Performance notes
- `to_pyca()` is zero-copy: the already-held DER bytes are passed by reference to
`cryptography`'s `load_der_x509_certificate`. No re-encoding or copying occurs.
- `from_pyca()` has a fast path: when the PyCA object was originally created by synta's
`to_pyca()`, the `_synta_der_bytes` attribute is present and read back directly,
avoiding the `public_bytes(Encoding.DER)` call entirely.
- synta is typically 4–10× faster than `cryptography` for parsing and field access.
See also [PublicKey and PrivateKey](keys.md) for synta's native crypto API,
[X.509 Path Validation](x509-verification.md) for chain verification, and
[Performance](../dev/performance.md) for benchmark results.