synta-certificate 0.2.6

//! Shared NSS FFI types, constants, and extern declarations used across all
//! `nss_backend` submodules.
//!
//! Centralising every C-interop item here gives a single declaration per C
//! symbol, which eliminates `clashing_extern_declarations` warnings.  Each
//! submodule imports what it needs via `use super::ffi::…`.

use nss_sys::nspr::PRBool;
use nss_sys::{PK11SlotInfoStr, SECAlgorithmIDStr, SECItemStr, SECStatus};

// ── NSS OID tag type ──────────────────────────────────────────────────────────

/// NSS OID tag (`SECOidTag` in NSS headers).
pub(super) type SECOidTag = u32;

// ── PKCS#11 type aliases ──────────────────────────────────────────────────────

pub(super) type CKMechanismType = std::ffi::c_ulong;
pub(super) type CKAttributeType = std::ffi::c_ulong;
pub(super) type CKRsaPkcsMgfType = std::ffi::c_ulong;
pub(super) type CKRsaPkcsOaepSourceType = std::ffi::c_ulong;

// ── NSS hash algorithm OID tags (secoidt.h; stable since NSS 3.2) ─────────────

pub(super) const SEC_OID_MD5: SECOidTag = 3;
pub(super) const SEC_OID_SHA1: SECOidTag = 4;
pub(super) const SEC_OID_SHA224: SECOidTag = 238; // added NSS 3.9.2
pub(super) const SEC_OID_SHA256: SECOidTag = 191;
pub(super) const SEC_OID_SHA384: SECOidTag = 192;
pub(super) const SEC_OID_SHA512: SECOidTag = 193;
pub(super) const SEC_OID_SHA3_256: SECOidTag = 365; // added NSS 3.51
pub(super) const SEC_OID_SHA3_384: SECOidTag = 366; // added NSS 3.51
pub(super) const SEC_OID_SHA3_512: SECOidTag = 367; // added NSS 3.51

// ── NSS signature algorithm OID tags (secoidt.h; ML-DSA requires NSS ≥ 3.103) ─

pub(super) const SEC_OID_PKCS1_SHA256_WITH_RSA_ENCRYPTION: SECOidTag = 194;
pub(super) const SEC_OID_PKCS1_SHA384_WITH_RSA_ENCRYPTION: SECOidTag = 195;
pub(super) const SEC_OID_PKCS1_SHA512_WITH_RSA_ENCRYPTION: SECOidTag = 196;
pub(super) const SEC_OID_ANSIX962_ECDSA_SHA256_SIGNATURE: SECOidTag = 278;
pub(super) const SEC_OID_ANSIX962_ECDSA_SHA384_SIGNATURE: SECOidTag = 279;
pub(super) const SEC_OID_ANSIX962_ECDSA_SHA512_SIGNATURE: SECOidTag = 280;
pub(super) const SEC_OID_ED25519_SIGNATURE: SECOidTag = 373;
pub(super) const SEC_OID_ML_DSA_44: SECOidTag = 391;
pub(super) const SEC_OID_ML_DSA_65: SECOidTag = 392;
pub(super) const SEC_OID_ML_DSA_87: SECOidTag = 393;

// ── PKCS#11 mechanism constants ───────────────────────────────────────────────

// RSA mechanisms (PKCS#11 v2.40 §6.1).
pub(super) const CKM_RSA_PKCS: CKMechanismType = 0x0000_0001;
pub(super) const CKM_RSA_PKCS_OAEP: CKMechanismType = 0x0000_0009;
/// RSA key-pair generation mechanism (PKCS#11 v2.40 §6.1.1).
/// Pass a `PK11RsaGenParams` as the mechanism parameter.
pub(super) const CKM_RSA_PKCS_KEY_PAIR_GEN: CKMechanismType = 0x0000_0000;
/// RSA-PSS with SHA-256 hash-then-sign (PKCS#11 v2.40 §6.3.1).
/// Pass a [`CkRsaPkcsPssParams`] as the mechanism parameter.
pub(super) const CKM_SHA256_RSA_PKCS_PSS: CKMechanismType = 0x0000_0043;
/// RSA-PSS with SHA-512 hash-then-sign (PKCS#11 v2.40 §6.3.1).
/// Pass a [`CkRsaPkcsPssParams`] as the mechanism parameter.
pub(super) const CKM_SHA512_RSA_PKCS_PSS: CKMechanismType = 0x0000_0045;

/// EC key-pair generation for NIST / Brainpool curves (PKCS#11 v2.40 §2.3.5).
/// Pass an `SECItemStr` holding the DER-encoded named-curve OID as the parameter.
pub(super) const CKM_EC_KEY_PAIR_GEN: CKMechanismType = 0x0000_1040;
/// Edwards-curve key-pair generation for Ed25519 / Ed448 (PKCS#11 v3.0 §2.3.6).
/// Pass an `SECItemStr` holding the DER-encoded named-curve OID as the parameter.
pub(super) const CKM_EC_EDWARDS_KEY_PAIR_GEN: CKMechanismType = 0x0000_1055;
/// EdDSA sign/verify mechanism for Ed25519 and Ed448 (PKCS#11 v3.0 §2.3.6).
/// Pass a [`CkEddsaParams`] as the mechanism parameter.
pub(super) const CKM_EDDSA: CKMechanismType = 0x0000_1057;
/// ML-DSA key-pair generation (PKCS#11 v3.2).
/// Pass a `*mut c_ulong` pointing to a `CKP_ML_DSA_44/65/87` parameter set constant.
pub(super) const CKM_ML_DSA_KEY_PAIR_GEN: CKMechanismType = 0x0000_001C;

/// ML-DSA sign/verify mechanism (PKCS#11 v3.2, pure — message is not pre-hashed).
///
/// Pass a `SECItemStr` whose `data` points to a [`CkSignAdditionalContext`] and
/// whose `len` is `size_of::<CkSignAdditionalContext>()` as the mechanism parameter.
/// The `hash` / `data` argument to `PK11_SignWithMechanism` /
/// `PK11_VerifyWithMechanism` carries the raw message bytes.
pub(super) const CKM_ML_DSA: CKMechanismType = 0x0000_001D;

// ML-DSA parameter set types (CK_PARAMETER_SET_TYPE, PKCS#11 v3.2 §2.3.9).
pub(super) const CKP_ML_DSA_44: std::ffi::c_ulong = 1;
pub(super) const CKP_ML_DSA_65: std::ffi::c_ulong = 2;
pub(super) const CKP_ML_DSA_87: std::ffi::c_ulong = 3;

// ML-DSA hedging variants (CK_HEDGE_TYPE, PKCS#11 v3.2).
pub(super) type CkHedgeType = std::ffi::c_ulong;
/// Hedging preferred (randomised signing when the token supports it).
pub(super) const CKH_HEDGE_PREFERRED: CkHedgeType = 0x0000_0000;

/// Mechanism parameter for [`CKM_ML_DSA`] sign and verify operations.
///
/// Corresponds to `CK_SIGN_ADDITIONAL_CONTEXT` from PKCS#11 v3.2 §2.3.9.
#[repr(C)]
pub(super) struct CkSignAdditionalContext {
    /// Hedging strategy (`CKH_HEDGE_PREFERRED`, `CKH_HEDGE_REQUIRED`, or
    /// `CKH_DETERMINISTIC_REQUIRED`).
    pub hedge_variant: CkHedgeType,
    /// Context string bytes (may be an empty slice; pointer must be non-null
    /// even when `ul_context_len` is zero — use a 1-byte dummy in that case).
    pub p_context: *const u8,
    /// Length of `p_context` in bytes.
    pub ul_context_len: std::ffi::c_ulong,
}

/// Mechanism parameters for [`CKM_SHA256_RSA_PKCS_PSS`] and [`CKM_SHA512_RSA_PKCS_PSS`].
///
/// Corresponds to `CK_RSA_PKCS_PSS_PARAMS` from PKCS#11 v2.40 §6.3.3.
#[repr(C)]
pub(super) struct CkRsaPkcsPssParams {
    /// Hash algorithm used for PSS (e.g. `CKM_SHA256`).
    pub hash_alg: CKMechanismType,
    /// Mask generation function (e.g. `CKG_MGF1_SHA256`).
    pub mgf: CKRsaPkcsMgfType,
    /// Salt length in bytes (32 for SHA-256, 64 for SHA-512).
    pub s_len: std::ffi::c_ulong,
}

/// Boolean type alias for PKCS#11 `CK_BBOOL` (0 = false, non-zero = true).
pub(super) type CkBbool = u8;

/// Mechanism parameters for [`CKM_EDDSA`] (Ed25519 and Ed448).
///
/// Corresponds to `CK_EDDSA_PARAMS` from PKCS#11 v3.0 §2.3.6.
#[repr(C)]
pub(super) struct CkEddsaParams {
    /// Prehash flag: `0` = pure EdDSA (no prehash), `1` = HashEdDSA.
    pub ph_flag: CkBbool,
    /// Length of the context data in bytes (0 = no context).
    pub ul_context_data_len: std::ffi::c_ulong,
    /// Pointer to context data; may be null when `ul_context_data_len` is 0.
    pub p_context_data: *const u8,
}

// Hash mechanism types used in CK_RSA_PKCS_OAEP_PARAMS.hashAlg.
pub(super) const CKM_SHA_1: CKMechanismType = 0x0000_0220;
pub(super) const CKM_SHA224: CKMechanismType = 0x0000_0255;
pub(super) const CKM_SHA256: CKMechanismType = 0x0000_0250;
pub(super) const CKM_SHA384: CKMechanismType = 0x0000_0260;
pub(super) const CKM_SHA512: CKMechanismType = 0x0000_0270;

// HMAC mechanism types (PKCS#11 v2.40 §9.2).
pub(super) const CKM_MD5_HMAC: CKMechanismType = 0x0000_0211;
pub(super) const CKM_SHA_1_HMAC: CKMechanismType = 0x0000_0221;
pub(super) const CKM_SHA224_HMAC: CKMechanismType = 0x0000_0256;
pub(super) const CKM_SHA256_HMAC: CKMechanismType = 0x0000_0251;
pub(super) const CKM_SHA384_HMAC: CKMechanismType = 0x0000_0261;
pub(super) const CKM_SHA512_HMAC: CKMechanismType = 0x0000_0271;

// AES and 3DES-CBC mechanism types (PKCS#11 v2.40 §9.15 / §9.17).
pub(super) const CKM_AES_CBC: CKMechanismType = 0x0000_1022;
pub(super) const CKM_AES_CBC_PAD: CKMechanismType = 0x0000_1025;
/// AES-GCM (PKCS#11 v2.40 §9.15); param must point to a `CkAesGcmParams`.
pub(super) const CKM_AES_GCM: CKMechanismType = 0x0000_1087;
pub(super) const CKM_DES3_CBC: CKMechanismType = 0x0000_0122;
pub(super) const CKM_DES3_CBC_PAD: CKMechanismType = 0x0000_0125;

/// PKCS#11 v2.40 `CK_GCM_PARAMS` layout (includes `ulIvBits`, as NSS requires).
///
/// `CK_ULONG` = `c_ulong` (8 bytes on Linux x86-64).  The two pointer fields
/// (`iv_ptr`, `aad_ptr`) and the four `c_ulong` fields interleave uniformly on
/// the target platform; no padding is inserted by the compiler.
///
/// The `SECItemStr` that wraps this struct must use `siBuffer` as its type and
/// point directly at this struct for the duration of the PKCS#11 call.
#[repr(C)]
pub(super) struct CkAesGcmParams {
    pub iv_ptr: *const u8,
    pub iv_len: std::ffi::c_ulong,
    pub iv_bits: std::ffi::c_ulong,
    pub aad_ptr: *const u8,
    pub aad_len: std::ffi::c_ulong,
    pub tag_bits: std::ffi::c_ulong,
}

// MGF1 mask-generation function types (PKCS#11 v2.40 §6.3.3).
pub(super) const CKG_MGF1_SHA1: CKRsaPkcsMgfType = 0x0000_0001;
pub(super) const CKG_MGF1_SHA224: CKRsaPkcsMgfType = 0x0000_0005;
pub(super) const CKG_MGF1_SHA256: CKRsaPkcsMgfType = 0x0000_0002;
pub(super) const CKG_MGF1_SHA384: CKRsaPkcsMgfType = 0x0000_0003;
pub(super) const CKG_MGF1_SHA512: CKRsaPkcsMgfType = 0x0000_0004;

// PKCS#11 attribute types (§9.1).
pub(super) const CKA_ENCRYPT: CKAttributeType = 0x0000_0104;
pub(super) const CKA_DECRYPT: CKAttributeType = 0x0000_0105;

// Source type: CKZ_DATA_SPECIFIED — no label data (empty label).
pub(super) const CKZ_DATA_SPECIFIED: CKRsaPkcsOaepSourceType = 0x0000_0001;

// PK11Origin::PK11_OriginUnwrap (4) — key imported from an external value.
pub(super) const PK11_ORIGIN_UNWRAP: std::ffi::c_uint = 4;

// Key-usage bitmasks.
pub(super) const KU_DIGITAL_SIGNATURE: std::ffi::c_uint = 0x80;
pub(super) const KU_KEY_ENCIPHERMENT: std::ffi::c_uint = 0x20;

// ── NSS RSA key-generation parameters ────────────────────────────────────────

/// NSS RSA key generation parameters (`PK11RSAGenParams` in `<nss3/pk11pub.h>`).
#[repr(C)]
pub(super) struct PK11RsaGenParams {
    pub(super) key_size_in_bits: std::ffi::c_int,
    pub(super) pe: std::ffi::c_ulong,
}

// ── Opaque NSS key and context types ─────────────────────────────────────────

/// Opaque NSS private key type (matches `SECKEYPrivateKey` in NSS headers).
pub(super) enum SECKEYPrivateKeyStr {}

/// Opaque NSS public key type (matches `SECKEYPublicKey` in NSS headers).
pub(super) enum SECKEYPublicKeyStr {}

/// Opaque NSS `CERTSubjectPublicKeyInfo` type.
///
/// Used by `SECKEY_DecodeDERSubjectPublicKeyInfo` and `SECKEY_ExtractPublicKey`
/// to import RSA/EC public keys from SPKI DER without a crypto backend round-trip.
pub(super) enum CERTSubjectPublicKeyInfoStr {}

/// Opaque PKCS#11 symmetric key type (`PK11SymKey`).
pub(super) enum PK11SymKeyStr {}

/// Opaque PKCS#11 crypto context type (`PK11Context`).
pub(super) enum PK11ContextStr {}

// ── NSS key-list types (from <nss3/keythi.h>) ────────────────────────────────

/// NSPR doubly-linked list node (matches `PRCList` in `<nspr/prclist.h>`).
#[repr(C)]
pub(super) struct PRCList {
    pub(super) next: *mut PRCList,
    pub(super) prev: *mut PRCList,
}

/// NSS private key list returned by `PK11_ListPrivKeysInSlot`.
///
/// Layout matches `SECKEYPrivateKeyList` in `<nss3/keythi.h>`:
/// `{ PLArenaPool *arena; PRCList list; }`.
#[repr(C)]
pub(super) struct SECKEYPrivateKeyList {
    pub(super) arena: *mut std::ffi::c_void, // PLArenaPool* — opaque
    pub(super) list: PRCList,
}

/// A node in a `SECKEYPrivateKeyList`.
///
/// Layout matches `SECKEYPrivateKeyListNode` in `<nss3/keythi.h>`:
/// `{ PRCList links; SECKEYPrivateKey *key; PLArenaPool *arena; }`.
#[repr(C)]
pub(super) struct SECKEYPrivateKeyListNode {
    pub(super) links: PRCList,
    pub(super) key: *mut SECKEYPrivateKeyStr,
    pub(super) arena: *mut std::ffi::c_void, // PLArenaPool* — opaque
}

// ── PKCS#11 RSA-OAEP params (PKCS#11 v2.40 §6.1.2) ──────────────────────────

/// PKCS#11 `CK_RSA_PKCS_OAEP_PARAMS` struct.
#[repr(C)]
pub(super) struct CkRsaPkcsOaepParams {
    pub(super) hash_alg: CKMechanismType,
    pub(super) mgf: CKRsaPkcsMgfType,
    pub(super) source: CKRsaPkcsOaepSourceType,
    pub(super) p_source_data: *mut std::ffi::c_void,
    pub(super) ul_source_data_len: std::ffi::c_ulong,
}

// ── extern "C" declarations ───────────────────────────────────────────────────

extern "C" {
    // ── Slot management ───────────────────────────────────────────────────────

    /// Get the NSS internal slot (slot 1 — cryptographic services).
    pub(super) fn PK11_GetInternalSlot() -> *mut PK11SlotInfoStr;

    /// Release a slot reference obtained from `PK11_GetInternalSlot`.
    pub(super) fn PK11_FreeSlot(slot: *mut PK11SlotInfoStr);

    /// Find a PKCS#11 slot by its human-readable token label.
    ///
    /// Returns NULL if no slot with that label is found.  Caller must call
    /// `PK11_FreeSlot` on the returned non-null pointer.
    pub(super) fn PK11_FindSlotByName(name: *const std::ffi::c_char) -> *mut PK11SlotInfoStr;

    /// Authenticate to a token with the given PIN string.
    ///
    /// - `loadCerts` — pass `PR_TRUE` to load certificates from the token.
    /// - `wincx` — the PIN as a NUL-terminated C string, or NULL for no PIN.
    ///
    /// Returns `SECSuccess` on success.
    pub(super) fn PK11_Authenticate(
        slot: *mut PK11SlotInfoStr,
        loadCerts: PRBool,
        wincx: *const std::ffi::c_char,
    ) -> SECStatus;

    // ── Key-pair generation ───────────────────────────────────────────────────

    /// Generate a key pair in `slot` using PKCS#11 mechanism `type_`.
    ///
    /// For RSA, `param` points to a `PK11RsaGenParams` struct.
    /// For EC and Edwards keys, `param` points to an `SECItemStr` that holds
    /// the DER-encoded curve OID (named curve parameters).
    ///
    /// Returns a non-null `SECKEYPrivateKey *` on success.  The public key is
    /// written through `pubk`.  Both must be freed by the caller:
    /// `SECKEY_DestroyPrivateKey` / `SECKEY_DestroyPublicKey`.
    pub(super) fn PK11_GenerateKeyPair(
        slot: *mut PK11SlotInfoStr,
        type_: CKMechanismType,
        param: *mut std::ffi::c_void,
        pubk: *mut *mut SECKEYPublicKeyStr,
        is_perm: nss_sys::nspr::PRBool,
        is_sensitive: nss_sys::nspr::PRBool,
        wincx: *mut std::ffi::c_void,
    ) -> *mut SECKEYPrivateKeyStr;

    /// Export `priv_key` as an unencrypted PKCS#8 `PrivateKeyInfo` DER blob.
    ///
    /// Returns a heap-allocated `SECItem`.  The caller must free it with
    /// `SECITEM_FreeItem(item, PR_TRUE)`.  Returns NULL on failure.
    pub(super) fn PK11_ExportDERPrivateKeyInfo(
        priv_key: *mut SECKEYPrivateKeyStr,
        wincx: *mut std::ffi::c_void,
    ) -> *mut SECItemStr;

    // ── Private key management ────────────────────────────────────────────────

    /// Free an `SECKEYPrivateKey` returned by key-import or key-copy functions.
    pub(super) fn SECKEY_DestroyPrivateKey(key: *mut SECKEYPrivateKeyStr);

    /// Destroy an NSS public key returned by `SECKEY_ExtractPublicKey` or
    /// `SECKEY_ConvertToPublicKey`.
    pub(super) fn SECKEY_DestroyPublicKey(key: *mut SECKEYPublicKeyStr);

    /// Decode a DER-encoded `SubjectPublicKeyInfo` into an NSS struct.
    ///
    /// Returns a heap-allocated `CERTSubjectPublicKeyInfo`; free with
    /// `SECKEY_DestroySubjectPublicKeyInfo`.
    pub(super) fn SECKEY_DecodeDERSubjectPublicKeyInfo(
        spkider: *const SECItemStr,
    ) -> *mut CERTSubjectPublicKeyInfoStr;

    /// Free a `CERTSubjectPublicKeyInfo` returned by
    /// `SECKEY_DecodeDERSubjectPublicKeyInfo`.
    pub(super) fn SECKEY_DestroySubjectPublicKeyInfo(spki: *mut CERTSubjectPublicKeyInfoStr);

    /// Extract the public key from a decoded `CERTSubjectPublicKeyInfo`.
    ///
    /// Returns a heap-allocated `SECKEYPublicKey`; free with
    /// `SECKEY_DestroyPublicKey`.
    pub(super) fn SECKEY_ExtractPublicKey(
        spki: *const CERTSubjectPublicKeyInfoStr,
    ) -> *mut SECKEYPublicKeyStr;

    /// Return the RSA public key modulus length in bytes.
    ///
    /// Used to size the output buffer for `PK11_PubEncrypt`.
    pub(super) fn SECKEY_PublicKeyStrength(pubk: *const SECKEYPublicKeyStr) -> std::ffi::c_uint;

    /// Import a PKCS#8 `PrivateKeyInfo` DER blob into `slot` and return the
    /// resulting `SECKEYPrivateKey`.
    ///
    /// - `isPerm = PR_FALSE` — session key; not written to disk.
    /// - `isPrivate = PR_TRUE` — treat as a private key.
    /// - `usage` — key-usage bitmask: `KU_DIGITAL_SIGNATURE` or `KU_KEY_ENCIPHERMENT`.
    pub(super) fn PK11_ImportDERPrivateKeyInfoAndReturnKey(
        slot: *mut PK11SlotInfoStr,
        der_pki: *const SECItemStr,
        nickname: *const SECItemStr,
        public_value: *const SECItemStr,
        is_perm: PRBool,
        is_private: PRBool,
        usage: std::ffi::c_uint,
        privk: *mut *mut SECKEYPrivateKeyStr,
        wincx: *mut std::ffi::c_void,
    ) -> SECStatus;

    /// Import a raw symmetric key into `slot` for use with `mech`.
    ///
    /// `origin` must be `PK11_ORIGIN_UNWRAP` for externally-supplied key
    /// material.  `operation` selects the permitted key usage; use `CKA_SIGN`
    /// for HMAC and `CKA_ENCRYPT` / `CKA_DECRYPT` for block ciphers.
    pub(super) fn PK11_ImportSymKey(
        slot: *mut PK11SlotInfoStr,
        mech: CKMechanismType,
        origin: std::ffi::c_uint,
        operation: CKAttributeType,
        key: *const SECItemStr,
        wincx: *mut std::ffi::c_void,
    ) -> *mut PK11SymKeyStr;

    /// Free a `PK11SymKey` returned by `PK11_ImportSymKey`.
    pub(super) fn PK11_FreeSymKey(key: *mut PK11SymKeyStr);

    // ── PKCS#11 key-list operations ───────────────────────────────────────────

    /// Return a list of private keys in `slot` filtered by `nickname`.
    ///
    /// Pass `nickname = NULL` to list all keys.  Caller must free with
    /// `SECKEY_DestroyPrivateKeyList`.  Available since NSS 3.4.
    pub(super) fn PK11_ListPrivKeysInSlot(
        slot: *mut PK11SlotInfoStr,
        nickname: *mut std::ffi::c_char,
        wincx: *const std::ffi::c_void,
    ) -> *mut SECKEYPrivateKeyList;

    /// Free a `SECKEYPrivateKeyList` returned by `PK11_ListPrivKeysInSlot`.
    pub(super) fn SECKEY_DestroyPrivateKeyList(keys: *mut SECKEYPrivateKeyList);

    /// Copy a private key reference (increments the refcount).
    ///
    /// Used to extract a key from a list before the list is destroyed.
    /// Caller must free with `SECKEY_DestroyPrivateKey`.
    pub(super) fn SECKEY_CopyPrivateKey(
        privkey: *mut SECKEYPrivateKeyStr,
    ) -> *mut SECKEYPrivateKeyStr;

    /// Return the public key corresponding to a private key.
    ///
    /// Caller must free with `SECKEY_DestroyPublicKey`.
    pub(super) fn SECKEY_ConvertToPublicKey(
        privkey: *mut SECKEYPrivateKeyStr,
    ) -> *mut SECKEYPublicKeyStr;

    /// DER-encode the `SubjectPublicKeyInfo` of `pubkey` into an `SECItem`.
    ///
    /// Returned pointer is NSS-allocated; free with
    /// `SECITEM_FreeItem(item, PR_TRUE)`.
    pub(super) fn SECKEY_EncodeDERSubjectPublicKeyInfo(
        pubkey: *const SECKEYPublicKeyStr,
    ) -> *mut SECItemStr;

    // ── RSA encryption / decryption ───────────────────────────────────────────

    /// Encrypt using RSA public key `key` with mechanism `type_`.
    ///
    /// For `CKM_RSA_PKCS` pass `param = NULL`.
    /// For `CKM_RSA_PKCS_OAEP` pass `param` pointing to `CkRsaPkcsOaepParams`.
    /// `out` must be pre-allocated to at least `SECKEY_PublicKeyStrength(key)` bytes.
    pub(super) fn PK11_PubEncrypt(
        key: *mut SECKEYPublicKeyStr,
        type_: CKMechanismType,
        param: *mut SECItemStr,
        out: *mut u8,
        out_len: *mut std::ffi::c_uint,
        max_len: std::ffi::c_uint,
        data: *const u8,
        data_len: std::ffi::c_uint,
        wincx: *mut std::ffi::c_void,
    ) -> SECStatus;

    /// Decrypt using RSA private key `key` and mechanism `type_`.
    ///
    /// For `CKM_RSA_PKCS` pass `param = NULL`.
    /// For `CKM_RSA_PKCS_OAEP` pass `param` pointing to `CkRsaPkcsOaepParams`.
    pub(super) fn PK11_PrivDecrypt(
        key: *mut SECKEYPrivateKeyStr,
        type_: CKMechanismType,
        param: *mut SECItemStr,
        out: *mut u8,
        out_len: *mut std::ffi::c_uint,
        max_len: std::ffi::c_uint,
        data: *const u8,
        data_len: std::ffi::c_uint,
    ) -> SECStatus;

    // ── Signing ───────────────────────────────────────────────────────────────

    /// Hash-then-sign `buf[0..len]` with `pk` using `algid`.
    ///
    /// On success `result.data` is NSS-allocated; free with
    /// `SECITEM_FreeItem(&mut result, PR_FALSE)`.
    ///
    /// Suitable for RSA PKCS#1 v1.5, ECDSA, and ML-DSA.  Not suitable for
    /// EdDSA — use [`PK11_Sign`] for that instead.
    pub(super) fn SEC_SignData(
        result: *mut SECItemStr,
        buf: *const u8,
        len: std::ffi::c_int,
        pk: *mut SECKEYPrivateKeyStr,
        algid: SECOidTag,
    ) -> SECStatus;

    /// Sign `hash` with `key` using the key's native PKCS#11 mechanism.
    ///
    /// For EdDSA (`CKM_EDDSA`) `hash` holds the **raw message** (not a digest);
    /// the token hashes and signs atomically.  `sig` must be pre-allocated to
    /// at least `PK11_SignatureLen(key)` bytes.
    pub(super) fn PK11_Sign(
        key: *mut SECKEYPrivateKeyStr,
        sig: *mut SECItemStr,
        hash: *const SECItemStr,
    ) -> SECStatus;

    /// Return the maximum signature length in bytes for `key`.
    pub(super) fn PK11_SignatureLen(key: *const SECKEYPrivateKeyStr) -> std::ffi::c_int;

    /// Sign `hash` with `key` using an explicit PKCS#11 mechanism and parameters.
    ///
    /// For `CKM_ML_DSA`, `param` must be a `SECItemStr` whose `data` points to a
    /// [`CkSignAdditionalContext`] (len = `size_of::<CkSignAdditionalContext>()`).
    /// `sig` must be pre-allocated to at least `PK11_SignatureLen(key)` bytes.
    pub(super) fn PK11_SignWithMechanism(
        key: *mut SECKEYPrivateKeyStr,
        mechanism: CKMechanismType,
        param: *const SECItemStr,
        sig: *mut SECItemStr,
        hash: *const SECItemStr,
    ) -> SECStatus;

    // ── Verification ──────────────────────────────────────────────────────────

    /// Verify `data` against `sig` using `sig_alg`.
    ///
    /// Note: fails with `SEC_ERROR_INVALID_ALGORITHM` for Ed25519 due to a
    /// duplicate OID entry in NSS's internal table — use `PK11_Verify` for EdDSA.
    pub(super) fn VFY_VerifyDataWithAlgorithmID(
        buf: *const u8,
        len: std::ffi::c_int,
        key: *const SECKEYPublicKeyStr,
        sig: *const SECItemStr,
        sig_alg: *const SECAlgorithmIDStr,
        canon_alg: *const SECAlgorithmIDStr,
        wincx: *mut std::ffi::c_void,
    ) -> SECStatus;

    /// Verify `sig` over `hash` using `key`'s native PKCS#11 mechanism.
    ///
    /// For Ed25519 (`CKM_EDDSA`), `hash` holds the **raw message** (not a
    /// digest); NSS's softokn hashes and verifies atomically.
    pub(super) fn PK11_Verify(
        key: *mut SECKEYPublicKeyStr,
        sig: *const SECItemStr,
        hash: *const SECItemStr,
        wincx: *mut std::ffi::c_void,
    ) -> SECStatus;

    /// Verify `sig` over `hash` using an explicit PKCS#11 mechanism and parameters.
    ///
    /// For `CKM_ML_DSA`, `param` must be a `SECItemStr` whose `data` points to a
    /// [`CkSignAdditionalContext`] (len = `size_of::<CkSignAdditionalContext>()`).
    pub(super) fn PK11_VerifyWithMechanism(
        key: *mut SECKEYPublicKeyStr,
        mechanism: CKMechanismType,
        param: *const SECItemStr,
        sig: *const SECItemStr,
        hash: *const SECItemStr,
        wincx: *mut std::ffi::c_void,
    ) -> SECStatus;

    // ── Symmetric crypto context ──────────────────────────────────────────────

    /// Create a PKCS#11 crypto context backed by `sym_key`.
    ///
    /// `param` may be a zero-length `siBuffer` item for HMAC (no IV needed),
    /// or the IV as a `siBuffer` for AES-CBC / 3DES-CBC.
    pub(super) fn PK11_CreateContextBySymKey(
        mech: CKMechanismType,
        operation: CKAttributeType,
        sym_key: *mut PK11SymKeyStr,
        param: *const SECItemStr,
    ) -> *mut PK11ContextStr;

    /// Free a `PK11Context` allocated by `PK11_CreateContextBySymKey` or
    /// `PK11_CreateDigestContext`.
    pub(super) fn PK11_DestroyContext(context: *mut PK11ContextStr, freeit: PRBool);

    /// Feed data into a streaming crypto or hash context.
    pub(super) fn PK11_DigestOp(
        context: *mut PK11ContextStr,
        in_data: *const u8,
        len: std::ffi::c_uint,
    ) -> SECStatus;

    /// Finalise a streaming context and write the output.
    pub(super) fn PK11_DigestFinal(
        context: *mut PK11ContextStr,
        data: *mut u8,
        out_len: *mut std::ffi::c_uint,
        length: std::ffi::c_uint,
    ) -> SECStatus;

    /// Encrypt or decrypt one chunk in a streaming cipher context.
    ///
    /// `context` must have been created by `PK11_CreateContextBySymKey` and
    /// initialised by `PK11_DigestBegin`.
    pub(super) fn PK11_CipherOp(
        context: *mut PK11ContextStr,
        out: *mut u8,
        out_len: *mut std::ffi::c_int,
        maxout: std::ffi::c_int,
        data: *const u8,
        data_len: std::ffi::c_int,
    ) -> SECStatus;

    // ── Digest context ────────────────────────────────────────────────────────

    /// Create a PKCS#11 context for one-way hash computation.
    ///
    /// `hash_alg` is an `SECOidTag` for the desired hash algorithm
    /// (SEC_OID_SHA256, etc.).  Must be freed with
    /// `PK11_DestroyContext(ctx, PR_TRUE)`.
    pub(super) fn PK11_CreateDigestContext(hash_alg: SECOidTag) -> *mut PK11ContextStr;

    /// Initialize (or re-initialize) a hash or HMAC context.
    ///
    /// Required after `PK11_CreateDigestContext` (which leaves `init = PR_FALSE`)
    /// and after `PK11_CreateContextBySymKey`.  Calls `C_DigestInit`,
    /// `C_SignInit`, `C_EncryptInit`, or `C_DecryptInit` on the PKCS#11 session.
    pub(super) fn PK11_DigestBegin(cx: *mut PK11ContextStr) -> SECStatus;

    // ── One-shot hash ─────────────────────────────────────────────────────────

    /// Hash `len` bytes at `data` into `out` using algorithm `hash_alg`.
    ///
    /// Returns `SECSuccess` (0) on success.  Available since NSS 3.2.
    ///
    /// Note: does not support SHA-224 on Fedora NSS builds.  Use the streaming
    /// digest-context path (`PK11_CreateDigestContext`) when SHA-224 support
    /// is required.
    pub(super) fn PK11_HashBuf(
        hash_alg: SECOidTag,
        out: *mut u8,
        data: *const u8,
        len: std::ffi::c_int,
    ) -> SECStatus;

    // ── Random ────────────────────────────────────────────────────────────────

    /// Fill `buf` with `len` cryptographically random bytes.
    ///
    /// Returns `SECSuccess` on success.  Available since NSS 3.2.
    pub(super) fn PK11_GenerateRandom(buf: *mut u8, len: std::ffi::c_int) -> SECStatus;

    // ── SECItem management ────────────────────────────────────────────────────

    /// Free the `.data` buffer inside `item` (`freeit = PR_FALSE`) or the
    /// item struct itself (`freeit = PR_TRUE`).
    pub(super) fn SECITEM_FreeItem(item: *mut SECItemStr, freeit: PRBool);
}