synta 0.2.3

#ifndef SYNTA_H
#define SYNTA_H

/* Warning: This file is automatically generated by cbindgen. Do not modify manually. */

#include <stdarg.h>
#include <stdbool.h>
#include <stdint.h>
#include <stdlib.h>

/**
 * FFI error codes (C-compatible)
 */
typedef enum SyntaErrorCode {
    /**
     * Operation succeeded
     */
    SyntaErrorCode_Success = 0,
    /**
     * Invalid tag encoding
     */
    SyntaErrorCode_InvalidTag = 1,
    /**
     * Invalid length encoding
     */
    SyntaErrorCode_InvalidLength = 2,
    /**
     * Unexpected end of input
     */
    SyntaErrorCode_UnexpectedEof = 3,
    /**
     * Invalid encoding for the current mode
     */
    SyntaErrorCode_InvalidEncoding = 4,
    /**
     * Invalid integer encoding
     */
    SyntaErrorCode_InvalidInteger = 5,
    /**
     * Invalid OID encoding
     */
    SyntaErrorCode_InvalidOid = 6,
    /**
     * Invalid UTF-8 string
     */
    SyntaErrorCode_InvalidUtf8 = 7,
    /**
     * Invalid PrintableString characters
     */
    SyntaErrorCode_InvalidPrintableString = 8,
    /**
     * Invalid IA5String characters
     */
    SyntaErrorCode_InvalidIA5String = 9,
    /**
     * Invalid boolean encoding
     */
    SyntaErrorCode_InvalidBoolean = 10,
    /**
     * Invalid time format
     */
    SyntaErrorCode_InvalidTime = 11,
    /**
     * Invalid bit string encoding
     */
    SyntaErrorCode_InvalidBitString = 12,
    /**
     * Maximum nesting depth exceeded
     */
    SyntaErrorCode_MaxDepthExceeded = 13,
    /**
     * Maximum sequence elements exceeded
     */
    SyntaErrorCode_MaxSequenceElementsExceeded = 14,
    /**
     * Maximum length exceeded
     */
    SyntaErrorCode_MaxLengthExceeded = 15,
    /**
     * BER-specific violation (indefinite length in DER, etc.)
     */
    SyntaErrorCode_BerViolation = 16,
    /**
     * DER-specific violation
     */
    SyntaErrorCode_DerViolation = 17,
    /**
     * CER-specific violation
     */
    SyntaErrorCode_CerViolation = 18,
    /**
     * NULL pointer passed as argument
     */
    SyntaErrorCode_NullPointer = 19,
    /**
     * Invalid argument
     */
    SyntaErrorCode_InvalidArgument = 20,
    /**
     * Memory allocation failed
     */
    SyntaErrorCode_OutOfMemory = 21,
    /**
     * Integer overflow
     */
    SyntaErrorCode_IntegerOverflow = 22,
    /**
     * Integer underflow
     */
    SyntaErrorCode_IntegerUnderflow = 23,
    /**
     * Unknown or unhandled error
     */
    SyntaErrorCode_Unknown = 999,
} SyntaErrorCode;

/**
 * ASN.1 encoding rules
 */
typedef enum SyntaEncoding {
    /**
     * Distinguished Encoding Rules (deterministic)
     */
    SyntaEncoding_Der = 0,
    /**
     * Basic Encoding Rules (flexible)
     */
    SyntaEncoding_Ber = 1,
    /**
     * Canonical Encoding Rules (streaming)
     */
    SyntaEncoding_Cer = 2,
} SyntaEncoding;

/**
 * ASN.1 tag class
 */
typedef enum SyntaTagClass {
    /**
     * Universal class (0)
     */
    SyntaTagClass_Universal = 0,
    /**
     * Application class (1)
     */
    SyntaTagClass_Application = 1,
    /**
     * Context-specific class (2)
     */
    SyntaTagClass_ContextSpecific = 2,
    /**
     * Private class (3)
     */
    SyntaTagClass_Private = 3,
} SyntaTagClass;

/**
 * Opaque handle to a Certificate
 */
typedef struct SyntaCertificate {
    uint8_t _private[0];
} SyntaCertificate;

/**
 * C-compatible byte array with ownership tracking
 *
 * Layout (16 bytes on 64-bit, no tail padding):
 *   offset  0: data  (*const u8,  8 bytes)
 *   offset  8: len   (u32,        4 bytes)
 *   offset 12: owned (u32,        4 bytes)  0 = borrowed, 1 = owned
 */
typedef struct SyntaByteArray {
    /**
     * Pointer to the data (may be null if len is 0)
     */
    const uint8_t *data;
    /**
     * Length of the data in bytes (max ~4 GiB; sufficient for any ASN.1 element)
     */
    uint32_t len;
    /**
     * Ownership flag: 1 = caller must free with `synta_byte_array_free`, 0 = borrowed
     */
    uint32_t owned;
} SyntaByteArray;

/**
 * Opaque handle to a parsed CMS `SignedData`.
 *
 * Obtained as a borrowed pointer via [`synta_cms_content_info_get0_signed_data`].
 * Must **not** be freed; ownership belongs to the parent `SyntaCmsContentInfo`.
 * All getter pointers remain valid until the parent handle is freed.
 */
typedef struct SyntaCmsSignedData {
    uint8_t _private[0];
} SyntaCmsSignedData;

/**
 * Opaque handle to a parsed CMS `SignerInfo`.
 *
 * Obtain with [`synta_cms_signer_info_parse_der`] (directly) or by passing
 * the bytes from [`synta_cms_signed_data_get_signer_info_der`] to it.
 * Release with [`synta_cms_signer_info_free`].
 */
typedef struct SyntaCmsSignerInfo {
    uint8_t _private[0];
} SyntaCmsSignerInfo;

/**
 * Opaque handle to a parsed CMS `EnvelopedData`.
 *
 * Obtained as a borrowed pointer via [`synta_cms_content_info_get0_enveloped_data`].
 * Must **not** be freed; ownership belongs to the parent `SyntaCmsContentInfo`.
 */
typedef struct SyntaCmsEnvelopedData {
    uint8_t _private[0];
} SyntaCmsEnvelopedData;

/**
 * Opaque handle to a parsed CMS `EncryptedData`.
 *
 * Obtained as a borrowed pointer via [`synta_cms_content_info_get0_encrypted_data`].
 * Must **not** be freed; ownership belongs to the parent `SyntaCmsContentInfo`.
 */
typedef struct SyntaCmsEncryptedData {
    uint8_t _private[0];
} SyntaCmsEncryptedData;

/**
 * Opaque handle to a parsed CMS `DigestedData`.
 *
 * Obtained as a borrowed pointer via [`synta_cms_content_info_get0_digested_data`].
 * Must **not** be freed; ownership belongs to the parent `SyntaCmsContentInfo`.
 */
typedef struct SyntaCmsDigestedData {
    uint8_t _private[0];
} SyntaCmsDigestedData;

/**
 * Opaque handle to a parsed CMS `ContentInfo`.
 *
 * Obtain with [`synta_cms_content_info_parse_der`]; release with
 * [`synta_cms_content_info_free`].
 *
 * ## `get0_*` pointer ownership
 *
 * Pointers returned by `synta_cms_content_info_get0_*` functions are
 * **borrowed from this handle**.  They are valid only while the
 * `SyntaCmsContentInfo` is alive and must **not** be passed to the
 * corresponding `synta_cms_*_free` function.  Free only the
 * `SyntaCmsContentInfo` itself with `synta_cms_content_info_free`.
 *
 * This follows the OpenSSL `get0_` convention for borrowed internal pointers,
 * distinguishable from owned (`get1_`) pointers by the naming convention.
 */
typedef struct SyntaCmsContentInfo {
    uint8_t _private[0];
} SyntaCmsContentInfo;

/**
 * Opaque handle to a parsed X.509 CRL.
 */
typedef struct SyntaCrl {
    uint8_t _private[0];
} SyntaCrl;

/**
 * Opaque handle to a parsed PKCS#10 CSR.
 */
typedef struct SyntaCsr {
    uint8_t _private[0];
} SyntaCsr;

/**
 * Opaque handle to a Decoder
 */
typedef struct SyntaDecoder {
    uint8_t _private[0];
} SyntaDecoder;

/**
 * Decoder configuration (C-compatible).
 *
 * All three limits are `size_t` (`usize`) on both sides of the FFI boundary,
 * keeping the struct layout consistent across 32-bit and 64-bit platforms.
 */
typedef struct SyntaDecoderConfig {
    /**
     * Maximum ASN.1 nesting depth (number of nested SEQUENCE/SET levels).
     */
    uintptr_t max_depth;
    /**
     * Maximum number of elements in a SEQUENCE or SET.
     */
    uintptr_t max_sequence_elements;
    /**
     * Maximum length of any single primitive element, in bytes.
     */
    uintptr_t max_length;
} SyntaDecoderConfig;

/**
 * C-compatible ASN.1 tag
 *
 * **C compatibility note:** `constructed` is mapped to `bool` by cbindgen,
 * which requires `<stdbool.h>` in C99.  The generated header includes a
 * `cpp_compat` guard so C++ consumers see `bool` without the header.
 * C89 callers should treat the field as a one-byte integer (0 = false,
 * non-zero = true).
 */
typedef struct SyntaTag {
    /**
     * Tag class
     */
    enum SyntaTagClass class_;
    /**
     * Whether the tag is constructed (true) or primitive (false).
     * Requires `<stdbool.h>` in C99; treat as `uint8_t` in C89.
     */
    bool constructed;
    /**
     * Tag number
     */
    unsigned int number;
} SyntaTag;

/**
 * Opaque handle to an Integer
 */
typedef struct SyntaInteger {
    uint8_t _private[0];
} SyntaInteger;

/**
 * Opaque handle to an OctetString
 */
typedef struct SyntaOctetString {
    uint8_t _private[0];
} SyntaOctetString;

/**
 * Opaque handle to an ObjectIdentifier
 */
typedef struct SyntaObjectIdentifier {
    uint8_t _private[0];
} SyntaObjectIdentifier;

/**
 * Opaque handle to an Encoder
 */
typedef struct SyntaEncoder {
    uint8_t _private[0];
} SyntaEncoder;

/**
 * Opaque handle to a parsed OCSP response.
 */
typedef struct SyntaOcsp {
    uint8_t _private[0];
} SyntaOcsp;

/**
 * Opaque handle to an ordered list of DER buffers.
 *
 * Created by [`synta_pem_to_der`], [`synta_pkcs7_certs_from_der`], or
 * [`synta_pkcs12_certs_from_der`].  Must be freed with [`synta_der_list_free`].
 */
typedef struct SyntaDerList {
    uint8_t _private[0];
} SyntaDerList;

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

/**
 * Parse an X.509 certificate from DER bytes
 *
 * # Safety
 *
 * - `data` must be a valid pointer to DER-encoded certificate bytes
 * - The returned certificate must be freed with `synta_certificate_free`
 *
 * # Returns
 *
 * Returns a pointer to the certificate, or NULL on error.
 */
struct SyntaCertificate *synta_certificate_parse_der(const uint8_t *data, uintptr_t len);

/**
 * Free a certificate
 *
 * # Safety
 *
 * - `cert` must be a valid pointer returned from `synta_certificate_parse_der`
 * - This function must only be called once for each certificate
 */
void synta_certificate_free(struct SyntaCertificate *cert);

/**
 * Get certificate version (v1=0, v2=1, v3=2)
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns Success if version is present, or error if not present (defaults to v1=0)
 */
enum SyntaErrorCode synta_certificate_get_version(const struct SyntaCertificate *cert,
                                                  int64_t *out);

/**
 * Get certificate serial number
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns the serial number bytes as a borrowed slice.
 * The data is valid while `cert` is alive; do not free with `synta_byte_array_free`.
 */
enum SyntaErrorCode synta_certificate_get_serial_number(const struct SyntaCertificate *cert,
                                                        struct SyntaByteArray *out);

/**
 * Get the certificate signature algorithm OID as a dotted-decimal string.
 *
 * # Return value
 *
 * | Condition                          | Return value            |
 * |------------------------------------|-------------------------|
 * | `cert` is null                     | `0`                     |
 * | `buffer` is null or `buffer_len` 0 | required size (incl. `\0`) |
 * | `buffer_len` too small             | required size (incl. `\0`) |
 * | success                            | bytes written, excl. `\0` |
 *
 * When the buffer is too small the return value is the minimum `buffer_len`
 * needed for a subsequent successful call (size-query / retry pattern):
 *
 * ```c
 * size_t needed = synta_certificate_get_signature_algorithm(cert, NULL, 0);
 * char *buf = malloc(needed);
 * synta_certificate_get_signature_algorithm(cert, buf, needed);
 * ```
 *
 * The OID string is computed at most once per certificate and cached;
 * repeated calls incur no formatting cost.
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate, or `NULL`.
 * - If `buffer` is non-null it must point to a writable buffer of at least
 *   `buffer_len` bytes.
 */
uintptr_t synta_certificate_get_signature_algorithm(const struct SyntaCertificate *cert,
                                                    char *buffer,
                                                    uintptr_t buffer_len);

/**
 * Get certificate signature algorithm AlgorithmIdentifier (full raw DER)
 *
 * Returns the complete DER encoding of the inner AlgorithmIdentifier SEQUENCE,
 * including the algorithm OID and any parameters (e.g. NULL for RSA,
 * named curve OID for EC public keys in SubjectPublicKeyInfo).
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns a borrowed slice of the pre-computed AlgorithmIdentifier DER bytes.
 * The data is valid while `cert` is alive; do not free with `synta_byte_array_free`.
 */
enum SyntaErrorCode synta_certificate_get_signature_algorithm_der(const struct SyntaCertificate *cert,
                                                                  struct SyntaByteArray *out);

/**
 * Get outer certificate signature algorithm AlgorithmIdentifier (full raw DER)
 *
 * Returns the complete DER encoding of the outer AlgorithmIdentifier SEQUENCE.
 * Must match the inner TBS copy for a well-formed certificate.
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns a borrowed slice of the pre-computed outer AlgorithmIdentifier DER bytes.
 * The data is valid while `cert` is alive; do not free with `synta_byte_array_free`.
 */
enum SyntaErrorCode synta_certificate_get_outer_signature_algorithm_der(const struct SyntaCertificate *cert,
                                                                        struct SyntaByteArray *out);

/**
 * Get certificate issuer DN (raw DER bytes)
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns a zero-copy borrowed slice into the original DER buffer.
 * The data is valid while `cert` is alive; do not free with `synta_byte_array_free`.
 */
enum SyntaErrorCode synta_certificate_get_issuer_der(const struct SyntaCertificate *cert,
                                                     struct SyntaByteArray *out);

/**
 * Get certificate subject DN (raw DER bytes)
 *
 * # Safety
 *
 * - `cert` must be a valid pointer to a certificate
 * - `out` must be a valid pointer
 *
 * # Returns
 *
 * Returns a zero-copy borrowed slice into the original DER buffer.
 * The data is valid while `cert` is alive; do not free with `synta_byte_array_free`.
 */
enum SyntaErrorCode synta_certificate_get_subject_der(const struct SyntaCertificate *cert,
                                                      struct SyntaByteArray *out);

/**
 * Get the `CMSVersion` integer for `SignedData`.
 *
 * RFC 5652 §5.1 defines the version as:
 *
 * - `1` — all signers use `v1` `SignerInfo` and no `AttributeCertificateV2`
 *   entries appear in `certificates`
 * - `3` — at least one signer uses `v3` `SignerInfo` (subjectKeyIdentifier),
 *   or an `AttributeCertificateV2` appears in `certificates`
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_version(const struct SyntaCmsSignedData *sd,
                                                      int64_t *out);

/**
 * Get the encapsulated content type OID as a NUL-terminated dotted-decimal string.
 *
 * Returns the number of bytes written (excluding the NUL terminator) on
 * success, or the required buffer size (including NUL) when `buffer` is null
 * or too small.  Returns 0 when `sd` is null.
 *
 * # Safety
 *
 * - `sd` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_signed_data_get_encap_content_type(const struct SyntaCmsSignedData *sd,
                                                       char *buffer,
                                                       uintptr_t buffer_len);

/**
 * Get the encapsulated content bytes (the `eContent` OCTET STRING value).
 *
 * The returned slice points directly into the parsed buffer; it is valid
 * while `sd` is alive.  Returns zero-length output when `eContent` is absent.
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_encap_content(const struct SyntaCmsSignedData *sd,
                                                            struct SyntaByteArray *out);

/**
 * Get the raw content bytes of the `certificates` field (`[0] IMPLICIT`).
 *
 * These are the **value** bytes captured during IMPLICIT decoding (no
 * context-tag prefix).  Returns zero-length output when the field is absent.
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_certificates_der(const struct SyntaCmsSignedData *sd,
                                                               struct SyntaByteArray *out);

/**
 * Get the raw content bytes of the `crls` field (`[1] IMPLICIT`).
 *
 * Returns zero-length output when the field is absent.
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_crls_der(const struct SyntaCmsSignedData *sd,
                                                       struct SyntaByteArray *out);

/**
 * Get the number of `SignerInfo` elements.
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_signer_info_count(const struct SyntaCmsSignedData *sd,
                                                                uintptr_t *out);

/**
 * Get the DER encoding of the `SignerInfo` at position `index`.
 *
 * Returns a borrowed [`SyntaByteArray`] pointing into a pre-encoded buffer;
 * the slice is valid while `sd` is alive.  The bytes are a complete,
 * self-contained `SignerInfo` SEQUENCE that can be passed directly to
 * [`synta_cms_signer_info_parse_der`] for field-level access.
 *
 * Returns [`SyntaErrorCode::InvalidArgument`] when `index` is out of bounds.
 *
 * # Safety
 *
 * - `sd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signed_data_get_signer_info_der(const struct SyntaCmsSignedData *sd,
                                                              uintptr_t index,
                                                              struct SyntaByteArray *out);

/**
 * Parse a BER/DER-encoded CMS `SignerInfo` SEQUENCE.
 *
 * The typical workflow is to obtain the per-element DER bytes via
 * [`synta_cms_signed_data_get_signer_info_der`] and pass them here, rather
 * than constructing a standalone `SignerInfo` buffer from scratch.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to at least `len` readable bytes.
 * - The returned handle must be freed with [`synta_cms_signer_info_free`].
 *
 * Returns `NULL` on parse error; call `synta_get_last_error_message()` for
 * details.
 */
struct SyntaCmsSignerInfo *synta_cms_signer_info_parse_der(const uint8_t *data, uintptr_t len);

/**
 * Free a `SyntaCmsSignerInfo` handle.
 *
 * # Safety
 *
 * - `si` must be a valid pointer returned from [`synta_cms_signer_info_parse_der`].
 * - Must be called at most once.
 */
void synta_cms_signer_info_free(struct SyntaCmsSignerInfo *si);

/**
 * Get the `CMSVersion` integer for `SignerInfo`.
 *
 * RFC 5652 §5.3 defines the version as:
 *
 * - `1` — `sid` contains an `IssuerAndSerialNumber` (SEQUENCE, tag `0x30`)
 * - `3` — `sid` contains a `SubjectKeyIdentifier` (`[0] IMPLICIT` OCTET STRING)
 *
 * The version determines how to interpret the bytes returned by
 * [`synta_cms_signer_info_get_sid_der`].
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_version(const struct SyntaCmsSignerInfo *si,
                                                      int64_t *out);

/**
 * Get the raw content bytes of the `sid` (SignerIdentifier) field.
 *
 * `SignerIdentifier` is a CHOICE between `IssuerAndSerialNumber` (version 1)
 * and `SubjectKeyIdentifier` (version 3, `[0] IMPLICIT` OCTET STRING).  The
 * field is stored as `RawDer`; the returned bytes are the **content** bytes
 * captured during decoding — without any outer context-tag prefix.
 *
 * Callers should check the version first to decide how to interpret the bytes:
 *
 * - version `1`: bytes are a raw `IssuerAndSerialNumber` SEQUENCE (tag `0x30`)
 * - version `3`: bytes are a raw `OCTET STRING` value (key identifier)
 *
 * The slice is valid while `si` is alive; do not free with
 * `synta_byte_array_free`.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_sid_der(const struct SyntaCmsSignerInfo *si,
                                                      struct SyntaByteArray *out);

/**
 * Get the full DER encoding of the `digestAlgorithm` AlgorithmIdentifier.
 *
 * Returns a borrowed slice into a pre-encoded buffer; valid while `si` is alive.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_digest_algorithm_der(const struct SyntaCmsSignerInfo *si,
                                                                   struct SyntaByteArray *out);

/**
 * Get the `digestAlgorithm` OID as a NUL-terminated dotted-decimal string.
 *
 * Uses the size-query / retry pattern.  Returns 0 when `si` is null.
 *
 * # Safety
 *
 * - `si` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_signer_info_get_digest_algorithm_oid(const struct SyntaCmsSignerInfo *si,
                                                         char *buffer,
                                                         uintptr_t buffer_len);

/**
 * Get the raw content bytes of the `signedAttrs` field (`[0] IMPLICIT`).
 *
 * These are the value bytes captured during IMPLICIT decoding (no context-tag
 * prefix).  Returns zero-length output when absent.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_signed_attrs_der(const struct SyntaCmsSignerInfo *si,
                                                               struct SyntaByteArray *out);

/**
 * Get the full DER encoding of the `signatureAlgorithm` AlgorithmIdentifier.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_signature_algorithm_der(const struct SyntaCmsSignerInfo *si,
                                                                      struct SyntaByteArray *out);

/**
 * Get the `signatureAlgorithm` OID as a NUL-terminated dotted-decimal string.
 *
 * Uses the size-query / retry pattern.  Returns 0 when `si` is null.
 *
 * # Safety
 *
 * - `si` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_signer_info_get_signature_algorithm_oid(const struct SyntaCmsSignerInfo *si,
                                                            char *buffer,
                                                            uintptr_t buffer_len);

/**
 * Get the raw bytes of the `signature` OCTET STRING value.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_signature(const struct SyntaCmsSignerInfo *si,
                                                        struct SyntaByteArray *out);

/**
 * Get the raw content bytes of the `unsignedAttrs` field (`[1] IMPLICIT`).
 *
 * Returns zero-length output when absent.
 *
 * # Safety
 *
 * - `si` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_signer_info_get_unsigned_attrs_der(const struct SyntaCmsSignerInfo *si,
                                                                 struct SyntaByteArray *out);

/**
 * Get the `CMSVersion` integer for `EnvelopedData`.
 *
 * RFC 5652 §6.1 defines the version based on the recipient info types
 * present:
 *
 * - `0` — all recipients use `KeyTransRecipientInfo` v0, no originator info
 * - `2` — `KeyAgreeRecipientInfo` or `KEKRecipientInfo` present, no originator info
 * - `3` — `PasswordRecipientInfo` or `OtherRecipientInfo` present, or originator info present
 * - `4` — `KeyTransRecipientInfo` v2 present
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_enveloped_data_get_version(const struct SyntaCmsEnvelopedData *ed,
                                                         int64_t *out);

/**
 * Get the raw content bytes of the `recipientInfos` SET OF.
 *
 * `recipientInfos` is stored as `RawDer`; the returned slice is the captured
 * content bytes.  Valid while `ed` is alive.
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_enveloped_data_get_recipient_infos_der(const struct SyntaCmsEnvelopedData *ed,
                                                                     struct SyntaByteArray *out);

/**
 * Get the encrypted content type OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `ed` is null.
 *
 * # Safety
 *
 * - `ed` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_enveloped_data_get_content_type(const struct SyntaCmsEnvelopedData *ed,
                                                    char *buffer,
                                                    uintptr_t buffer_len);

/**
 * Get the full DER of the `contentEncryptionAlgorithm` AlgorithmIdentifier.
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_enveloped_data_get_content_encryption_algorithm_der(const struct SyntaCmsEnvelopedData *ed,
                                                                                  struct SyntaByteArray *out);

/**
 * Get the `contentEncryptionAlgorithm` OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `ed` is null.
 *
 * # Safety
 *
 * - `ed` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_enveloped_data_get_content_encryption_algorithm_oid(const struct SyntaCmsEnvelopedData *ed,
                                                                        char *buffer,
                                                                        uintptr_t buffer_len);

/**
 * Get the encrypted content bytes (the `encryptedContent` `[0] IMPLICIT` value).
 *
 * Returns zero-length output when absent.
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_enveloped_data_get_encrypted_content(const struct SyntaCmsEnvelopedData *ed,
                                                                   struct SyntaByteArray *out);

/**
 * Get the `CMSVersion` integer for `EncryptedData`.
 *
 * RFC 5652 §8 defines:
 *
 * - `0` — no unprotected attributes or attributes use only v0 types
 * - `2` — unprotected attributes include an `AttributeCertificateV2`
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_encrypted_data_get_version(const struct SyntaCmsEncryptedData *ed,
                                                         int64_t *out);

/**
 * Get the encrypted content type OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `ed` is null.
 *
 * # Safety
 *
 * - `ed` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_encrypted_data_get_content_type(const struct SyntaCmsEncryptedData *ed,
                                                    char *buffer,
                                                    uintptr_t buffer_len);

/**
 * Get the full DER of the `contentEncryptionAlgorithm` AlgorithmIdentifier.
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_encrypted_data_get_content_encryption_algorithm_der(const struct SyntaCmsEncryptedData *ed,
                                                                                  struct SyntaByteArray *out);

/**
 * Get the `contentEncryptionAlgorithm` OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `ed` is null.
 *
 * # Safety
 *
 * - `ed` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_encrypted_data_get_content_encryption_algorithm_oid(const struct SyntaCmsEncryptedData *ed,
                                                                        char *buffer,
                                                                        uintptr_t buffer_len);

/**
 * Get the encrypted content bytes (the `encryptedContent` `[0] IMPLICIT` value).
 *
 * Returns zero-length output when absent.
 *
 * # Safety
 *
 * - `ed` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_encrypted_data_get_encrypted_content(const struct SyntaCmsEncryptedData *ed,
                                                                   struct SyntaByteArray *out);

/**
 * Decrypt the `encryptedContent` of a CMS `EncryptedData` using the provided
 * symmetric key.
 *
 * The content encryption algorithm and its parameters (IV etc.) are read from
 * the `AlgorithmIdentifier` embedded in `ed`.  Decryption uses the
 * `synta_certificate::CmsDecryptor` trait internally:
 *
 * - When `synta-ffi` is built **with** the `openssl` feature, the
 *   OpenSSL-backed implementation is used and supports `id-aes128-cbc`,
 *   `id-aes192-cbc`, and `id-aes256-cbc`.
 * - Without the `openssl` feature, this function always returns an error.
 *
 * On success, `*plaintext_out` is set to the decrypted plaintext and must be
 * freed with [`synta_byte_array_free`].
 *
 * # Safety
 *
 * - `ed` must be a valid non-null pointer obtained from
 *   [`synta_cms_content_info_get0_encrypted_data`].
 * - `key` must be a valid pointer to at least `key_len` bytes.
 * - `plaintext_out` must be a valid non-null pointer.
 */
enum SyntaErrorCode synta_cms_encrypted_data_decrypt(const struct SyntaCmsEncryptedData *ed,
                                                     const uint8_t *key,
                                                     uintptr_t key_len,
                                                     struct SyntaByteArray *plaintext_out);

/**
 * Encrypt `plaintext` and assemble a DER-encoded CMS `EncryptedData` SEQUENCE.
 *
 * - `content_type_oid_der`: DER-encoded OID TLV (`06 xx ...`) for the
 *   content type (e.g. id-data).  Pass `NULL` to use the default `id-data`
 *   (1.2.840.113549.1.7.1).
 * - `enc_alg_oid_der`: DER-encoded OID TLV for the content-encryption
 *   algorithm (e.g. `id-aes128-cbc`).  Must not be `NULL`.
 * - `key` / `key_len`: raw symmetric key bytes.
 * - `plaintext` / `plaintext_len`: bytes to encrypt.
 * - `der_out`: receives an owned [`SyntaByteArray`] containing the
 *   complete `EncryptedData` DER on success.  Must be freed with
 *   [`synta_byte_array_free`].
 *
 * Requires the `openssl` feature; returns [`SyntaErrorCode::Unknown`] with a
 * descriptive error message otherwise.
 *
 * # Safety
 *
 * - `enc_alg_oid_der`, `key`, `plaintext`, and `der_out` must be valid
 *   non-null pointers.
 * - `content_type_oid_der` may be null to select the `id-data` default.
 */
enum SyntaErrorCode synta_cms_encrypted_data_create(const uint8_t *plaintext,
                                                    uintptr_t plaintext_len,
                                                    const uint8_t *key,
                                                    uintptr_t key_len,
                                                    const uint8_t *content_type_oid_der,
                                                    uintptr_t content_type_oid_der_len,
                                                    const uint8_t *enc_alg_oid_der,
                                                    uintptr_t enc_alg_oid_der_len,
                                                    struct SyntaByteArray *der_out);

/**
 * Get the `CMSVersion` integer for `DigestedData`.
 *
 * RFC 5652 §7 defines:
 *
 * - `0` — `eContentType` is `id-data`
 * - `2` — `eContentType` is any other OID
 *
 * # Safety
 *
 * - `dd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_digested_data_get_version(const struct SyntaCmsDigestedData *dd,
                                                        int64_t *out);

/**
 * Get the full DER of the `digestAlgorithm` AlgorithmIdentifier.
 *
 * # Safety
 *
 * - `dd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_digested_data_get_digest_algorithm_der(const struct SyntaCmsDigestedData *dd,
                                                                     struct SyntaByteArray *out);

/**
 * Get the `digestAlgorithm` OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `dd` is null.
 *
 * # Safety
 *
 * - `dd` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_digested_data_get_digest_algorithm_oid(const struct SyntaCmsDigestedData *dd,
                                                           char *buffer,
                                                           uintptr_t buffer_len);

/**
 * Get the encapsulated content type OID as a NUL-terminated dotted-decimal string.
 *
 * Returns 0 when `dd` is null.
 *
 * # Safety
 *
 * - `dd` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_digested_data_get_encap_content_type(const struct SyntaCmsDigestedData *dd,
                                                         char *buffer,
                                                         uintptr_t buffer_len);

/**
 * Get the encapsulated content bytes (the `eContent` OCTET STRING value).
 *
 * Returns zero-length output when absent.
 *
 * # Safety
 *
 * - `dd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_digested_data_get_encap_content(const struct SyntaCmsDigestedData *dd,
                                                              struct SyntaByteArray *out);

/**
 * Get the raw bytes of the `digest` OCTET STRING value.
 *
 * # Safety
 *
 * - `dd` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_cms_digested_data_get_digest(const struct SyntaCmsDigestedData *dd,
                                                       struct SyntaByteArray *out);

/**
 * Parse a BER/DER-encoded CMS `ContentInfo` SEQUENCE.
 *
 * Unlike the type-specific parse functions, this function accepts the **full
 * `ContentInfo`** (outer `SEQUENCE`, `contentType` OID, and `[0] EXPLICIT`
 * wrapper) and dispatches automatically to the appropriate inner-type parser.
 * This is the Synta equivalent of OpenSSL's `d2i_CMS_ContentInfo`.
 *
 * | Content type OID           | Name                | Accessor                                     |
 * |----------------------------|---------------------|----------------------------------------------|
 * | `1.2.840.113549.1.7.2`     | `id-signedData`     | `synta_cms_content_info_get0_signed_data`    |
 * | `1.2.840.113549.1.7.3`     | `id-envelopedData`  | `synta_cms_content_info_get0_enveloped_data` |
 * | `1.2.840.113549.1.7.6`     | `id-encryptedData`  | `synta_cms_content_info_get0_encrypted_data` |
 * | `1.2.840.113549.1.7.5`     | `id-digestedData`   | `synta_cms_content_info_get0_digested_data`  |
 *
 * Other content types parse successfully — `synta_cms_content_info_get_content_type`
 * still returns the OID, but all `get0_*` accessors return `NULL`.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to at least `len` readable bytes.
 * - The returned handle must be freed with [`synta_cms_content_info_free`].
 *
 * Returns `NULL` on parse error; call `synta_get_last_error_message()` for
 * the error detail.
 */
struct SyntaCmsContentInfo *synta_cms_content_info_parse_der(const uint8_t *data,
                                                             uintptr_t len);

/**
 * Free a `SyntaCmsContentInfo` handle and all inner content.
 *
 * Any `*const Synta*` pointers previously returned by `get0_*` functions on
 * this handle become invalid after this call.
 *
 * # Safety
 *
 * - `ci` must be a valid pointer returned from
 *   [`synta_cms_content_info_parse_der`], or `NULL` (no-op).
 * - Do **not** free borrowed `get0_*` pointers separately; free only `ci`.
 */
void synta_cms_content_info_free(struct SyntaCmsContentInfo *ci);

/**
 * Get the outer `contentType` OID as a NUL-terminated dotted-decimal string.
 *
 * Returns the `contentType` of the `ContentInfo` envelope — e.g.
 * `1.2.840.113549.1.7.2` for `id-signedData` — not the encapsulated content
 * type inside a `SignedData`.  This is the Synta equivalent of OpenSSL's
 * `CMS_get0_type`.
 *
 * Uses the size-query / retry pattern:
 * - Returns `bytes_written` (excluding NUL) on success.
 * - Returns `len + 1` (required buffer size including NUL) when `buffer` is
 *   `NULL` or `buffer_len` is too small.
 * - Returns `0` when `ci` is `NULL`.
 *
 * # Safety
 *
 * - `ci` must be a valid non-null pointer.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_cms_content_info_get_content_type(const struct SyntaCmsContentInfo *ci,
                                                  char *buffer,
                                                  uintptr_t buffer_len);

/**
 * Return a **borrowed** pointer to the inner `SignedData`, or `NULL`.
 *
 * Returns `NULL` if the `contentType` is not `id-signedData`
 * (`1.2.840.113549.1.7.2`).
 *
 * The returned `*const SyntaCmsSignedData` may be passed to all
 * `synta_cms_signed_data_get_*` accessor functions.  Do **not** call
 * `synta_cms_signed_data_free` on it — the memory is owned by the
 * `SyntaCmsContentInfo` handle and freed by `synta_cms_content_info_free`.
 *
 * This follows the OpenSSL `get0_` convention: the pointer is borrowed from
 * the parent handle (`*const`, not `*mut`) and must not be independently freed.
 *
 * # Safety
 *
 * - `ci` must be a valid non-null pointer.
 * - The returned pointer is valid only while `ci` is alive.
 */
const struct SyntaCmsSignedData *synta_cms_content_info_get0_signed_data(const struct SyntaCmsContentInfo *ci);

/**
 * Return a **borrowed** pointer to the inner `EnvelopedData`, or `NULL`.
 *
 * Returns `NULL` if the `contentType` is not `id-envelopedData`
 * (`1.2.840.113549.1.7.3`).
 *
 * Do **not** call `synta_cms_enveloped_data_free` on the returned pointer.
 * See [`synta_cms_content_info_get0_signed_data`] for full ownership semantics.
 *
 * # Safety
 *
 * - `ci` must be a valid non-null pointer.
 * - The returned pointer is valid only while `ci` is alive.
 */
const struct SyntaCmsEnvelopedData *synta_cms_content_info_get0_enveloped_data(const struct SyntaCmsContentInfo *ci);

/**
 * Return a **borrowed** pointer to the inner `EncryptedData`, or `NULL`.
 *
 * Returns `NULL` if the `contentType` is not `id-encryptedData`
 * (`1.2.840.113549.1.7.6`).
 *
 * Do **not** call `synta_cms_encrypted_data_free` on the returned pointer.
 * See [`synta_cms_content_info_get0_signed_data`] for full ownership semantics.
 *
 * # Safety
 *
 * - `ci` must be a valid non-null pointer.
 * - The returned pointer is valid only while `ci` is alive.
 */
const struct SyntaCmsEncryptedData *synta_cms_content_info_get0_encrypted_data(const struct SyntaCmsContentInfo *ci);

/**
 * Return a **borrowed** pointer to the inner `DigestedData`, or `NULL`.
 *
 * Returns `NULL` if the `contentType` is not `id-digestedData`
 * (`1.2.840.113549.1.7.5`).
 *
 * Do **not** call `synta_cms_digested_data_free` on the returned pointer.
 * See [`synta_cms_content_info_get0_signed_data`] for full ownership semantics.
 *
 * # Safety
 *
 * - `ci` must be a valid non-null pointer.
 * - The returned pointer is valid only while `ci` is alive.
 */
const struct SyntaCmsDigestedData *synta_cms_content_info_get0_digested_data(const struct SyntaCmsContentInfo *ci);

/**
 * Parse an X.509 CRL from DER bytes.
 *
 * Returns NULL on parse error; free with [`synta_crl_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaCrl *synta_crl_parse_der(const uint8_t *data, uintptr_t len);

/**
 * Parse an X.509 CRL from PEM bytes (first block only).
 *
 * Returns NULL on error; free with [`synta_crl_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaCrl *synta_crl_parse_pem(const uint8_t *data, uintptr_t len);

/**
 * Free a CRL returned by a `synta_crl_parse_*` function.
 *
 * # Safety
 *
 * - `crl` must be a valid pointer, or NULL.  Must be called exactly once.
 */
void synta_crl_free(struct SyntaCrl *crl);

/**
 * Get the CRL issuer distinguished name as raw DER bytes.
 *
 * Returns a borrowed slice valid while `crl` is alive.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_issuer_der(const struct SyntaCrl *crl,
                                             struct SyntaByteArray *out);

/**
 * Get the CRL signature algorithm AlgorithmIdentifier as raw DER bytes.
 *
 * Returns a borrowed slice valid while `crl` is alive.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_signature_algorithm_der(const struct SyntaCrl *crl,
                                                          struct SyntaByteArray *out);

/**
 * Get the CRL signature value as raw DER bytes (BIT STRING with tag).
 *
 * Returns a borrowed slice valid while `crl` is alive.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_signature_value_der(const struct SyntaCrl *crl,
                                                      struct SyntaByteArray *out);

/**
 * Get the CRL thisUpdate time as raw DER bytes.
 *
 * Returns a borrowed slice valid while `crl` is alive.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_this_update_der(const struct SyntaCrl *crl,
                                                  struct SyntaByteArray *out);

/**
 * Get the CRL nextUpdate time as raw DER bytes.
 *
 * Returns a borrowed slice valid while `crl` is alive, or a zero-length
 * array (`out->len == 0`) if nextUpdate is absent.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_next_update_der(const struct SyntaCrl *crl,
                                                  struct SyntaByteArray *out);

/**
 * Get the number of revoked certificate entries in the CRL.
 *
 * Returns 0 for an absent or empty `revokedCertificates` sequence.
 *
 * # Safety
 *
 * - `crl` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_crl_get_revoked_count(const struct SyntaCrl *crl, uintptr_t *out);

/**
 * Parse a PKCS#10 CSR from DER bytes.
 *
 * Returns NULL on parse error; free with [`synta_csr_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaCsr *synta_csr_parse_der(const uint8_t *data, uintptr_t len);

/**
 * Parse a PKCS#10 CSR from PEM bytes (first block only).
 *
 * Returns NULL on error; free with [`synta_csr_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaCsr *synta_csr_parse_pem(const uint8_t *data, uintptr_t len);

/**
 * Free a CSR returned by a `synta_csr_parse_*` function.
 *
 * # Safety
 *
 * - `csr` must be a valid pointer, or NULL.  Must be called exactly once.
 */
void synta_csr_free(struct SyntaCsr *csr);

/**
 * Get the CSR version (v1 = 0).
 *
 * # Safety
 *
 * - `csr` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_csr_get_version(const struct SyntaCsr *csr, int64_t *out);

/**
 * Get the CSR subject distinguished name as raw DER bytes.
 *
 * Returns a borrowed slice valid while `csr` is alive.
 *
 * # Safety
 *
 * - `csr` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_csr_get_subject_der(const struct SyntaCsr *csr,
                                              struct SyntaByteArray *out);

/**
 * Get the CSR signature algorithm AlgorithmIdentifier as raw DER bytes.
 *
 * Returns a borrowed slice valid while `csr` is alive.
 *
 * # Safety
 *
 * - `csr` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_csr_get_signature_algorithm_der(const struct SyntaCsr *csr,
                                                          struct SyntaByteArray *out);

/**
 * Get the CSR signature as raw DER bytes (BIT STRING with tag).
 *
 * Returns a borrowed slice valid while `csr` is alive.
 *
 * # Safety
 *
 * - `csr` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_csr_get_signature_der(const struct SyntaCsr *csr,
                                                struct SyntaByteArray *out);

/**
 * Get the CSR SubjectPublicKeyInfo as raw DER bytes.
 *
 * Returns a borrowed slice valid while `csr` is alive.
 *
 * # Safety
 *
 * - `csr` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_csr_get_public_key_der(const struct SyntaCsr *csr,
                                                 struct SyntaByteArray *out);

/**
 * Create a new decoder
 *
 * # Safety
 *
 * - `data` must be a valid pointer to a byte array of length `len`
 * - The data must remain valid for the lifetime of the decoder
 * - The returned decoder must be freed with `synta_decoder_free`
 *
 * # Returns
 *
 * Returns a pointer to the decoder, or NULL on error.
 */
struct SyntaDecoder *synta_decoder_new(const uint8_t *data,
                                       uintptr_t len,
                                       enum SyntaEncoding encoding);

/**
 * Create a new decoder with custom configuration
 *
 * # Safety
 *
 * - `data` must be a valid pointer to a byte array of length `len`
 * - `config` must be a valid pointer to a SyntaDecoderConfig
 * - The data must remain valid for the lifetime of the decoder
 * - The returned decoder must be freed with `synta_decoder_free`
 *
 * # Returns
 *
 * Returns a pointer to the decoder, or NULL on error.
 */
struct SyntaDecoder *synta_decoder_new_with_config(const uint8_t *data,
                                                   uintptr_t len,
                                                   enum SyntaEncoding encoding,
                                                   const struct SyntaDecoderConfig *config);

/**
 * Free a decoder
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer returned from `synta_decoder_new` or
 *   `synta_decoder_new_with_config`
 * - This function must only be called once for each decoder
 * - After calling this function, the decoder pointer is invalid
 */
void synta_decoder_free(struct SyntaDecoder *decoder);

/**
 * Get the number of remaining bytes in the decoder
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 */
uintptr_t synta_decoder_remaining(const struct SyntaDecoder *decoder);

/**
 * Check if the decoder is at the end of input
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 */
bool synta_decoder_at_end(const struct SyntaDecoder *decoder);

/**
 * Peek at the next tag without consuming it
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a SyntaTag
 */
enum SyntaErrorCode synta_decoder_peek_tag(const struct SyntaDecoder *decoder,
                                           struct SyntaTag *out);

/**
 * Decode a boolean value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a bool
 */
enum SyntaErrorCode synta_decode_boolean(struct SyntaDecoder *decoder, bool *out);

/**
 * Decode an integer value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the integer pointer
 * - The returned integer must be freed with `synta_integer_free`
 */
enum SyntaErrorCode synta_decode_integer(struct SyntaDecoder *decoder, struct SyntaInteger **out);

/**
 * Decode a NULL value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 */
enum SyntaErrorCode synta_decode_null(struct SyntaDecoder *decoder);

/**
 * Decode a REAL (f64) value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to an f64
 */
enum SyntaErrorCode synta_decode_real(struct SyntaDecoder *decoder, double *out);

/**
 * Decode an octet string value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_octet_string(struct SyntaDecoder *decoder,
                                              struct SyntaOctetString **out);

/**
 * Decode a UTF8String value (universal tag 12) into a `SyntaOctetString*`.
 *
 * Returns the raw content bytes without UTF-8 validation.  The bytes may
 * not be well-formed UTF-8.  Use `synta_decode_utf8_string` if you need the
 * decoder to enforce valid UTF-8 encoding.
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_utf8_string_os(struct SyntaDecoder *decoder,
                                                struct SyntaOctetString **out);

/**
 * Decode a PrintableString value (universal tag 19) into a `SyntaOctetString*`.
 *
 * Returns the raw content bytes without character-set validation.  The bytes
 * may contain characters outside the PrintableString alphabet.  Use
 * `synta_decode_printable_string` if you need the decoder to enforce the
 * allowed character set.
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_printable_string_os(struct SyntaDecoder *decoder,
                                                     struct SyntaOctetString **out);

/**
 * Decode an IA5String value (universal tag 22) into a `SyntaOctetString*`.
 *
 * Returns the raw content bytes without character-set validation.  The bytes
 * may contain code points above 127.  Use `synta_decode_ia5_string` if you
 * need the decoder to enforce the ASCII range.
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_ia5_string_os(struct SyntaDecoder *decoder,
                                               struct SyntaOctetString **out);

/**
 * Decode a UTCTime value (universal tag 23) into a `SyntaOctetString*`.
 *
 * Returns the raw content bytes without time-string syntax validation.  The
 * bytes may not represent a valid UTCTime.  The caller is responsible for
 * parsing and validating the time string if correctness matters.
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_utctime_os(struct SyntaDecoder *decoder,
                                            struct SyntaOctetString **out);

/**
 * Decode a GeneralizedTime value (universal tag 24) into a `SyntaOctetString*`.
 *
 * Returns the raw content bytes without time-string syntax validation.  The
 * bytes may not represent a valid GeneralizedTime.  The caller is responsible
 * for parsing and validating the time string if correctness matters.
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the octet string pointer
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
enum SyntaErrorCode synta_decode_generalized_time_os(struct SyntaDecoder *decoder,
                                                     struct SyntaOctetString **out);

/**
 * Decode a bit string value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a SyntaByteArray
 * - `unused_bits` must be a valid pointer to receive the unused bits count
 * - The returned byte array is owned and must be freed with `synta_byte_array_free`
 */
enum SyntaErrorCode synta_decode_bit_string(struct SyntaDecoder *decoder,
                                            struct SyntaByteArray *out,
                                            uint8_t *unused_bits);

/**
 * Decode an object identifier value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the OID pointer
 * - The returned OID must be freed with `synta_oid_free`
 */
enum SyntaErrorCode synta_decode_object_identifier(struct SyntaDecoder *decoder,
                                                   struct SyntaObjectIdentifier **out);

/**
 * Decode a UTF-8 string value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a SyntaByteArray
 * - The returned byte array is owned and must be freed with `synta_byte_array_free`
 */
enum SyntaErrorCode synta_decode_utf8_string(struct SyntaDecoder *decoder,
                                             struct SyntaByteArray *out);

/**
 * Decode a PrintableString value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a SyntaByteArray
 * - The returned byte array is owned and must be freed with `synta_byte_array_free`
 */
enum SyntaErrorCode synta_decode_printable_string(struct SyntaDecoder *decoder,
                                                  struct SyntaByteArray *out);

/**
 * Decode an IA5String value
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to a SyntaByteArray
 * - The returned byte array is owned and must be freed with `synta_byte_array_free`
 */
enum SyntaErrorCode synta_decode_ia5_string(struct SyntaDecoder *decoder,
                                            struct SyntaByteArray *out);

/**
 * Enter a SEQUENCE and return a new decoder for its contents
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the new decoder pointer
 * - The returned decoder must be freed with `synta_decoder_free`
 */
enum SyntaErrorCode synta_decoder_enter_sequence(struct SyntaDecoder *decoder,
                                                 struct SyntaDecoder **out);

/**
 * Enter a SET and return a new decoder for its contents
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the new decoder pointer
 * - The returned decoder must be freed with `synta_decoder_free`
 */
enum SyntaErrorCode synta_decoder_enter_set(struct SyntaDecoder *decoder,
                                            struct SyntaDecoder **out);

/**
 * Enter a constructed type with a specific tag
 *
 * # Safety
 *
 * - `decoder` must be a valid pointer to a decoder
 * - `out` must be a valid pointer to receive the new decoder pointer
 * - The returned decoder must be freed with `synta_decoder_free`
 */
enum SyntaErrorCode synta_decoder_enter_constructed(struct SyntaDecoder *decoder,
                                                    struct SyntaTag tag,
                                                    struct SyntaDecoder **out);

/**
 * Create a new encoder
 *
 * # Safety
 *
 * The returned encoder must be freed with `synta_encoder_free`
 */
struct SyntaEncoder *synta_encoder_new(enum SyntaEncoding encoding);

/**
 * Finish encoding and consume the encoder, returning the encoded bytes.
 *
 * **The encoder is destroyed by this call.**  The `encoder` pointer is
 * invalid after `synta_encoder_finish` returns, regardless of whether the
 * call succeeds or fails.  Do **not** pass the same pointer to
 * `synta_encoder_free` afterwards — that would be a double-free (undefined
 * behaviour).  The typical usage pattern is:
 *
 * ```c
 * SyntaEncoder *enc = synta_encoder_new(SyntaEncoding_Der);
 * // ... encode values ...
 * SyntaByteArray result;
 * SyntaErrorCode err = synta_encoder_finish(enc, &result);
 * enc = NULL;  // pointer is now invalid; set to NULL immediately
 * if (err != SyntaErrorCode_Success) { // handle error
 *     // ...
 * }
 * // use result ...
 * synta_byte_array_free(&result);
 * ```
 *
 * # Safety
 *
 * - `encoder` must be a valid, non-null pointer returned by `synta_encoder_new`.
 * - `out` must be a valid, non-null pointer to a `SyntaByteArray`.
 * - The encoder is **consumed** (destroyed) by this call.  The pointer must
 *   not be dereferenced or passed to any function (including
 *   `synta_encoder_free`) after this call returns.
 * - On success, the byte array written to `*out` is owned by the caller and
 *   must be freed with `synta_byte_array_free`.
 * - On failure, `*out` is left unchanged; call `synta_get_last_error_message`
 *   for details.
 */
enum SyntaErrorCode synta_encoder_finish(struct SyntaEncoder *encoder, struct SyntaByteArray *out);

/**
 * Discard an encoder without finishing it.
 *
 * Use this to clean up an encoder when encoding has been abandoned (e.g.
 * after an error).  Do **not** call this after `synta_encoder_finish` —
 * `synta_encoder_finish` already destroys the encoder, so calling
 * `synta_encoder_free` on the same pointer would be a double-free (undefined
 * behaviour).
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer returned by `synta_encoder_new`, **or**
 *   `NULL` (a null pointer is silently ignored).
 * - This function must only be called once per encoder.
 * - Must **not** be called if `synta_encoder_finish` has already been called
 *   with this pointer — that function destroys the encoder.
 */
void synta_encoder_free(struct SyntaEncoder *encoder);

/**
 * Encode a boolean value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 */
enum SyntaErrorCode synta_encode_boolean(struct SyntaEncoder *encoder, bool value);

/**
 * Encode an integer value from an Integer object
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `integer` must be a valid pointer to an Integer
 */
enum SyntaErrorCode synta_encode_integer(struct SyntaEncoder *encoder,
                                         const struct SyntaInteger *integer);

/**
 * Encode an integer value from an i64
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 */
enum SyntaErrorCode synta_encode_integer_i64(struct SyntaEncoder *encoder, int64_t value);

/**
 * Encode a NULL value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 */
enum SyntaErrorCode synta_encode_null(struct SyntaEncoder *encoder);

/**
 * Encode a REAL (f64) value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 */
enum SyntaErrorCode synta_encode_real(struct SyntaEncoder *encoder, double value);

/**
 * Encode an octet string value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_octet_string(struct SyntaEncoder *encoder,
                                              const uint8_t *data,
                                              uintptr_t len);

/**
 * Encode a UTF8String value (universal tag 12) from raw bytes.
 *
 * Unlike `synta_encode_utf8_string`, this function does not require the data to
 * be null-terminated.  The data is written as-is; no UTF-8 validation is
 * performed because the library stores string values as raw byte arrays.
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_utf8_string_bytes(struct SyntaEncoder *encoder,
                                                   const uint8_t *data,
                                                   uintptr_t len);

/**
 * Encode a PrintableString value (universal tag 19) from raw bytes.
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_printable_string_bytes(struct SyntaEncoder *encoder,
                                                        const uint8_t *data,
                                                        uintptr_t len);

/**
 * Encode an IA5String value (universal tag 22) from raw bytes.
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_ia5_string_bytes(struct SyntaEncoder *encoder,
                                                  const uint8_t *data,
                                                  uintptr_t len);

/**
 * Encode a UTCTime value (universal tag 23) from raw bytes.
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_utctime_bytes(struct SyntaEncoder *encoder,
                                               const uint8_t *data,
                                               uintptr_t len);

/**
 * Encode a GeneralizedTime value (universal tag 24) from raw bytes.
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 */
enum SyntaErrorCode synta_encode_generalized_time_bytes(struct SyntaEncoder *encoder,
                                                        const uint8_t *data,
                                                        uintptr_t len);

/**
 * Encode a bit string value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `data` must be a valid pointer to a byte array of length `len`, or NULL if len is 0
 * - `unused_bits` must be less than 8
 */
enum SyntaErrorCode synta_encode_bit_string(struct SyntaEncoder *encoder,
                                            const uint8_t *data,
                                            uintptr_t len,
                                            uint8_t unused_bits);

/**
 * Encode an object identifier value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `oid` must be a valid pointer to an ObjectIdentifier
 */
enum SyntaErrorCode synta_encode_object_identifier(struct SyntaEncoder *encoder,
                                                   const struct SyntaObjectIdentifier *oid);

/**
 * Encode a UTF-8 string value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `str` must be a valid null-terminated C string
 */
enum SyntaErrorCode synta_encode_utf8_string(struct SyntaEncoder *encoder, const char *str);

/**
 * Encode a PrintableString value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `str` must be a valid null-terminated C string
 */
enum SyntaErrorCode synta_encode_printable_string(struct SyntaEncoder *encoder, const char *str);

/**
 * Encode an IA5String value
 *
 * # Safety
 *
 * - `encoder` must be a valid pointer to an encoder
 * - `str` must be a valid null-terminated C string
 */
enum SyntaErrorCode synta_encode_ia5_string(struct SyntaEncoder *encoder, const char *str);

/**
 * Open a SEQUENCE and return an encoder handle for writing its contents.
 *
 * **`*out` aliases `encoder` — they point to the same object.**
 * This means:
 * - Write child elements by passing `*out` to encode functions.
 * - Close the SEQUENCE by calling `synta_encoder_end_constructed(*out)`.
 * - Do **not** call `synta_encoder_free` or `synta_encoder_finish` on
 *   `encoder` while the SEQUENCE is still open; that would destroy the shared
 *   object and leave `*out` dangling.
 * - Nested calls (`synta_encoder_start_sequence(*out, &inner)`) are allowed;
 *   close the innermost SEQUENCE first.
 *
 * # Safety
 *
 * - `encoder` must be a valid, non-null pointer to a live encoder.
 * - `out` must be a valid, non-null pointer to a `*mut SyntaEncoder`.
 * - `*out` must not be passed to `synta_encoder_free` or
 *   `synta_encoder_finish`; use `synta_encoder_end_constructed` instead.
 */
enum SyntaErrorCode synta_encoder_start_sequence(struct SyntaEncoder *encoder,
                                                 struct SyntaEncoder **out);

/**
 * Open a SET and return an encoder handle for writing its contents.
 *
 * **`*out` aliases `encoder` — they point to the same object.**
 * See `synta_encoder_start_sequence` for the full aliasing contract and
 * usage rules; the same constraints apply here.
 *
 * # Safety
 *
 * - `encoder` must be a valid, non-null pointer to a live encoder.
 * - `out` must be a valid, non-null pointer to a `*mut SyntaEncoder`.
 * - `*out` must not be passed to `synta_encoder_free` or
 *   `synta_encoder_finish`; use `synta_encoder_end_constructed` instead.
 */
enum SyntaErrorCode synta_encoder_start_set(struct SyntaEncoder *encoder,
                                            struct SyntaEncoder **out);

/**
 * Open a constructed element with an arbitrary tag and return an encoder
 * handle for writing its contents.
 *
 * **`*out` aliases `encoder` — they point to the same object.**
 * See `synta_encoder_start_sequence` for the full aliasing contract and
 * usage rules; the same constraints apply here.
 *
 * # Safety
 *
 * - `encoder` must be a valid, non-null pointer to a live encoder.
 * - `out` must be a valid, non-null pointer to a `*mut SyntaEncoder`.
 * - `*out` must not be passed to `synta_encoder_free` or
 *   `synta_encoder_finish`; use `synta_encoder_end_constructed` instead.
 */
enum SyntaErrorCode synta_encoder_start_constructed(struct SyntaEncoder *encoder,
                                                    struct SyntaTag tag,
                                                    struct SyntaEncoder **out);

/**
 * Close the innermost open constructed element and back-patch its length.
 *
 * Pass the `*out` pointer returned by `synta_encoder_start_sequence`,
 * `synta_encoder_start_set`, or `synta_encoder_start_constructed`.
 * Because `*out` aliases the parent encoder, after this call the parent
 * encoder is ready to accept more elements at the same nesting level.
 *
 * # Safety
 *
 * - `encoder` must be a valid, non-null pointer to a live encoder that has an
 *   open constructed element (i.e. `synta_encoder_start_*` was called and not
 *   yet balanced by a matching `synta_encoder_end_constructed`).
 * - This function must be called exactly once for each `synta_encoder_start_*`
 *   call, in innermost-first order for nested constructed elements.
 */
enum SyntaErrorCode synta_encoder_end_constructed(struct SyntaEncoder *encoder);

/**
 * Get the last error message
 *
 * # Safety
 *
 * The returned pointer is valid until the next call to any function that sets an error,
 * or until the current thread exits. The caller must not free the pointer.
 *
 * Returns NULL if no error has occurred or if the error message is invalid.
 */
const char *synta_get_last_error_message(void);

/**
 * Clear the last error message
 */
void synta_clear_last_error(void);

/**
 * Get a static error message for an error code
 *
 * # Safety
 *
 * The returned pointer is always valid and points to a static string.
 * The caller must not free the pointer.
 */
const char *synta_error_message(enum SyntaErrorCode code);

/**
 * Create an Integer from an i64 value
 *
 * # Safety
 *
 * The returned integer must be freed with `synta_integer_free`
 */
struct SyntaInteger *synta_integer_new_i64(int64_t value);

/**
 * Create an Integer from a u64 value
 *
 * # Safety
 *
 * The returned integer must be freed with `synta_integer_free`
 */
struct SyntaInteger *synta_integer_new_u64(uint64_t value);

/**
 * Create an Integer from a DER two's-complement byte array.
 *
 * `data` must point to `len` bytes in DER INTEGER two's-complement encoding:
 * the most significant byte comes first and the sign is encoded in the
 * most-significant bit of the first byte (set = negative, clear = positive).
 * This is the same byte layout as the content octets of a DER INTEGER TLV.
 *
 * The `is_negative` parameter is accepted for API stability but is **not
 * used** — the sign is already encoded in the byte content.  Passing `true`
 * does **not** negate the value; the caller must supply the correct two's
 * complement bytes instead.
 *
 * # Safety
 *
 * - `data` must be a valid, non-null pointer to at least `len` bytes.
 * - The returned integer must be freed with `synta_integer_free`.
 */
struct SyntaInteger *synta_integer_new_bytes(const uint8_t *data, uintptr_t len, bool _is_negative);

/**
 * Convert an Integer to an i64 value
 *
 * # Safety
 *
 * - `integer` must be a valid pointer to an Integer
 * - `out` must be a valid pointer to an i64
 *
 * # Returns
 *
 * Returns Success if the integer fits in an i64, IntegerOverflow otherwise
 */
enum SyntaErrorCode synta_integer_to_i64(const struct SyntaInteger *integer, int64_t *out);

/**
 * Convert an Integer to a u64 value
 *
 * # Safety
 *
 * - `integer` must be a valid pointer to an Integer
 * - `out` must be a valid pointer to a u64
 *
 * # Returns
 *
 * Returns Success if the integer fits in a u64 and is non-negative, IntegerOverflow/IntegerUnderflow otherwise
 */
enum SyntaErrorCode synta_integer_to_u64(const struct SyntaInteger *integer,
                                         uint64_t *out);

/**
 * Convert an Integer to a byte array
 *
 * # Safety
 *
 * - `integer` must be a valid pointer to an Integer
 * - `out` must be a valid pointer to a SyntaByteArray
 * - The returned byte array is owned and must be freed with `synta_byte_array_free`
 */
enum SyntaErrorCode synta_integer_to_bytes(const struct SyntaInteger *integer,
                                           struct SyntaByteArray *out);

/**
 * Check if an Integer is negative
 *
 * # Safety
 *
 * - `integer` must be a valid pointer to an Integer
 */
bool synta_integer_is_negative(const struct SyntaInteger *integer);

/**
 * Free an Integer
 *
 * # Safety
 *
 * - `integer` must be a valid pointer returned from an integer creation function
 * - This function must only be called once for each integer
 */
void synta_integer_free(struct SyntaInteger *integer);

/**
 * Parse an OCSP response from DER bytes.
 *
 * Returns NULL on parse error; free with [`synta_ocsp_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaOcsp *synta_ocsp_parse_der(const uint8_t *data, uintptr_t len);

/**
 * Free an OCSP response returned by [`synta_ocsp_parse_der`].
 *
 * # Safety
 *
 * - `ocsp` must be a valid pointer, or NULL.  Must be called exactly once.
 */
void synta_ocsp_free(struct SyntaOcsp *ocsp);

/**
 * Get the OCSP response status as an RFC 6960 integer code.
 *
 * | Code | Status           |
 * |------|------------------|
 * | 0    | successful       |
 * | 1    | malformedRequest |
 * | 2    | internalError    |
 * | 3    | tryLater         |
 * | 5    | sigRequired      |
 * | 6    | unauthorized     |
 *
 * # Safety
 *
 * - `ocsp` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_ocsp_get_status_code(const struct SyntaOcsp *ocsp, int32_t *out);

/**
 * Write the OCSP response status name into `buffer` as a NUL-terminated string.
 *
 * Uses the same size-query convention as `synta_certificate_get_signature_algorithm`:
 * pass `NULL`/`0` to get the required buffer size (including the NUL terminator).
 * Returns bytes written (excluding NUL) on success, or 0 if `ocsp` is NULL.
 *
 * # Safety
 *
 * - `ocsp` must be a valid pointer, or NULL.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_ocsp_get_status(const struct SyntaOcsp *ocsp, char *buffer, uintptr_t buffer_len);

/**
 * Write the OCSP responseType OID (dotted-decimal) into `buffer`.
 *
 * Returns 0 if `ocsp` is NULL **or** if `responseBytes` is absent.
 * Uses the same size-query convention as [`synta_ocsp_get_status`].
 *
 * # Safety
 *
 * - `ocsp` must be a valid pointer, or NULL.
 * - If `buffer` is non-null it must point to `buffer_len` writable bytes.
 */
uintptr_t synta_ocsp_get_response_type_oid(const struct SyntaOcsp *ocsp,
                                           char *buffer,
                                           uintptr_t buffer_len);

/**
 * Get the raw content bytes of the OCSP `response` OCTET STRING.
 *
 * For a `successful` response this is typically the DER of a
 * `BasicOCSPResponse`.  Returns a zero-length array (`out->len == 0`) if
 * `responseBytes` is absent.  The returned slice is valid while `ocsp` is alive.
 *
 * # Safety
 *
 * - `ocsp` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_ocsp_get_response_bytes_der(const struct SyntaOcsp *ocsp,
                                                      struct SyntaByteArray *out);

/**
 * Create an OctetString from a byte array
 *
 * # Safety
 *
 * - `data` must be a valid pointer to a byte array of length `len`
 * - The returned octet string must be freed with `synta_octet_string_free`
 */
struct SyntaOctetString *synta_octet_string_new(const uint8_t *data, uintptr_t len);

/**
 * Get a pointer to the data in an OctetString
 *
 * # Safety
 *
 * - `octet_string` must be a valid pointer to an OctetString
 * - The returned pointer is valid only while the OctetString is alive
 */
const uint8_t *synta_octet_string_data(const struct SyntaOctetString *octet_string);

/**
 * Get the length of an OctetString
 *
 * # Safety
 *
 * - `octet_string` must be a valid pointer to an OctetString
 */
uintptr_t synta_octet_string_len(const struct SyntaOctetString *octet_string);

/**
 * Free an OctetString
 *
 * # Safety
 *
 * - `octet_string` must be a valid pointer returned from an octet string creation function
 * - This function must only be called once for each octet string
 */
void synta_octet_string_free(struct SyntaOctetString *octet_string);

/**
 * Create an OID from an array of components
 *
 * # Safety
 *
 * - `components` must be a valid pointer to an array of u32 values of length `len`
 * - The returned OID must be freed with `synta_oid_free`
 */
struct SyntaObjectIdentifier *synta_oid_new(const uint32_t *components, uintptr_t len);

/**
 * Create an OID from a string (e.g., "1.2.840.113549.1.1.1")
 *
 * # Safety
 *
 * - `str` must be a valid null-terminated C string
 * - The returned OID must be freed with `synta_oid_free`
 */
struct SyntaObjectIdentifier *synta_oid_from_string(const char *str);

/**
 * Convert an OID to its dotted-decimal string representation.
 *
 * # Return value
 *
 * | Condition                          | Return value            |
 * |------------------------------------|-------------------------|
 * | `oid` is null                      | `0` (error set)         |
 * | `buf` is null or `buf_len` is `0`  | required size (incl. `\0`) |
 * | `buf_len` too small                | required size (incl. `\0`) |
 * | success                            | bytes written, excl. `\0` |
 *
 * On a null `oid`, `synta_get_last_error_message()` returns a description.
 * On a too-small buffer, the return value is the minimum `buf_len` needed
 * for a subsequent successful call.  This makes the function usable for a
 * size-query / retry pattern:
 *
 * ```c
 * size_t needed = synta_oid_to_string(oid, NULL, 0);
 * char *buf = malloc(needed);
 * synta_oid_to_string(oid, buf, needed);
 * ```
 *
 * # Safety
 *
 * - `oid` must be a valid pointer to an OID, or `NULL`.
 * - If `buf` is non-null it must point to a writable buffer of at least
 *   `buf_len` bytes.
 */
uintptr_t synta_oid_to_string(const struct SyntaObjectIdentifier *oid,
                              char *buf,
                              uintptr_t buf_len);

/**
 * Get the OID components as an array
 *
 * # Safety
 *
 * - `oid` must be a valid pointer to an OID
 * - `out` must be a valid pointer to receive the components pointer
 * - `out_len` must be a valid pointer to receive the components count
 * - The returned pointer is valid only while the OID is alive
 */
enum SyntaErrorCode synta_oid_components(const struct SyntaObjectIdentifier *oid,
                                         const uint32_t **out,
                                         uintptr_t *out_len);

/**
 * Check if two OIDs are equal
 *
 * # Safety
 *
 * - `a` and `b` must be valid pointers to OIDs
 */
bool synta_oid_equals(const struct SyntaObjectIdentifier *a, const struct SyntaObjectIdentifier *b);

/**
 * Free an OID
 *
 * # Safety
 *
 * - `oid` must be a valid pointer returned from an OID creation function
 * - This function must only be called once for each OID
 */
void synta_oid_free(struct SyntaObjectIdentifier *oid);

/**
 * Decode all PEM blocks in `data` and return an opaque list of DER buffers.
 *
 * Returns `NULL` if no PEM block is found or `data` is `NULL`.
 * Free the returned list with [`synta_der_list_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes, or `NULL`.
 */
struct SyntaDerList *synta_pem_to_der(const uint8_t *data, uintptr_t len);

/**
 * Encode DER bytes as a PEM block; return the result as an owned byte array.
 *
 * The caller must free the returned `SyntaByteArray` with `synta_byte_array_free`.
 * Returns a zero-length array (`data = NULL`) on error.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` readable bytes.
 * - `label` must be a valid null-terminated UTF-8 C string.
 */
struct SyntaByteArray synta_der_to_pem(const uint8_t *data, uintptr_t len, const char *label);

/**
 * Return the number of DER buffers in `list`.  Returns 0 if `list` is NULL.
 *
 * # Safety
 *
 * - `list` must be a valid pointer returned by a synta function, or `NULL`.
 */
uintptr_t synta_der_list_count(const struct SyntaDerList *list);

/**
 * Write the DER bytes at `index` into `*out` as a borrowed slice.
 *
 * The returned slice is valid while `list` is alive; do **not** free it with
 * `synta_byte_array_free`.  Returns `InvalidArgument` if `index` is out of range.
 *
 * # Safety
 *
 * - `list` and `out` must be valid non-null pointers.
 */
enum SyntaErrorCode synta_der_list_get_der(const struct SyntaDerList *list,
                                           uintptr_t index,
                                           struct SyntaByteArray *out);

/**
 * Free a [`SyntaDerList`] returned by a synta function.
 *
 * # Safety
 *
 * - `list` must be a valid pointer, or `NULL`.  Must be called exactly once.
 */
void synta_der_list_free(struct SyntaDerList *list);

/**
 * Extract X.509 certificates from a DER/BER-encoded PKCS#7 / CMS SignedData blob.
 *
 * Returns an opaque list of DER-encoded certificates; free with
 * [`synta_der_list_free`].  Returns NULL on error.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaDerList *synta_pkcs7_certs_from_der(const uint8_t *data, uintptr_t len);

/**
 * Extract X.509 certificates from a PEM-encoded PKCS#7 / CMS SignedData blob.
 *
 * Strips the PEM envelope then calls the DER extractor on each block.
 * Returns an opaque list of DER-encoded certificates; free with
 * [`synta_der_list_free`].  Returns NULL on error or if no PEM block is found.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 */
struct SyntaDerList *synta_pkcs7_certs_from_pem(const uint8_t *data, uintptr_t len);

/**
 * Extract X.509 certificates from an unencrypted PKCS#12 archive.
 *
 * Supports archives with no MAC and archives that use an empty password.
 * Encrypted content bags require an OpenSSL-backed build; this function
 * uses the dependency-free `NoCrypto` backend and returns an error for any
 * encrypted safe content it encounters.
 *
 * `password` may be NULL (treated as an empty byte string).  Returns an
 * opaque list of DER-encoded certificates; free with [`synta_der_list_free`].
 * Returns NULL on error.
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 * - If `password` is non-null it must point to `password_len` readable bytes.
 */
struct SyntaDerList *synta_pkcs12_certs_from_der(const uint8_t *data,
                                                 uintptr_t len,
                                                 const uint8_t *password,
                                                 uintptr_t password_len);

/**
 * Auto-detect the encoding of `data` and return every X.509 certificate as a
 * DER blob.
 *
 * Inspects the raw bytes, detects PEM / PKCS#7 / PKCS#12 / raw DER encoding,
 * and collects all entries whose label contains `"CERTIFICATE"`.  This is
 * equivalent to calling `synta_pkcs7_certs_from_der`, `synta_pem_to_der`,
 * `synta_pkcs12_certs_from_der`, or handling a raw DER blob — depending on
 * what `data` actually contains.
 *
 * `password` applies to PKCS#12 archives.  Pass NULL or a zero-length slice
 * for password-less archives.  Encrypted PKCS#12 bags are silently skipped
 * (unencrypted certificates in the same archive are still returned); the
 * C FFI layer does not include an OpenSSL backend.
 *
 * Returns an owned `SyntaDerList *`; NULL on hard structural error.
 * Free with [`synta_der_list_free`].
 *
 * # Safety
 *
 * - `data` must be a valid pointer to `len` bytes.
 * - If `password` is non-null it must point to `password_len` readable bytes.
 */
struct SyntaDerList *synta_read_pki_file(const uint8_t *data,
                                         uintptr_t len,
                                         const uint8_t *password,
                                         uintptr_t password_len);

/**
 * Free a byte array (only if owned)
 *
 * # Safety
 *
 * - `array` must be a valid pointer to a SyntaByteArray
 * - This function must only be called once for each owned array
 */
void synta_byte_array_free(struct SyntaByteArray *array);

/**
 * Allocate a zeroed `SyntaByteArray` of `len` bytes from Rust's allocator.
 *
 * The returned array is owned (`owned = 1`) and must be freed with
 * [`synta_byte_array_free`].
 *
 * Returns an empty array with `data = NULL` if `len` is 0.
 */
struct SyntaByteArray synta_byte_array_alloc(uintptr_t len);

/**
 * Clone a byte array (creates an owned copy)
 *
 * # Safety
 *
 * - `array` must be a valid pointer to a SyntaByteArray
 * - The returned array must be freed with synta_byte_array_free
 */
struct SyntaByteArray synta_byte_array_clone(const struct SyntaByteArray *array);

#ifdef __cplusplus
}  // extern "C"
#endif  // __cplusplus

#endif  /* SYNTA_H */