feat: add blapi feature to bypass PKCS#11 in RecordProtection

Add `--features blapi` which replaces `RecordProtection`'s hot path from
`PK11_AEADOp` (PKCS#11 → softoken → freebl) to direct freebl calls
(`AES_AEAD`, `ChaCha20Poly1305_Encrypt/Decrypt`), eliminating the
substantial `sftk_SessionFromHandle` mutex and hash-table overheads.

Author: larseggert

Cargo.toml

@@ -124,6 +124,7 @@ verbose_file_reads = "warn"
 
 [features]
 bench = ["log/release_max_level_info"]
+blapi = []
 deny-warnings = []
 disable-encryption = []
 disable-random = []

build.rs

@@ -229,6 +229,9 @@ fn dynamic_link() {
     for lib in dynamic_libs {
         println!("cargo:rustc-link-lib=dylib={lib}");
     }
+    // freebl loader stub: routes AES_AEAD / ChaCha20Poly1305_* to libfreebl3
+    // at runtime, bypassing the PKCS#11 session overhead.
+    println!("cargo:rustc-link-lib=static=freebl");
 }
 
 fn static_link() {
@@ -409,6 +412,9 @@ fn pkg_config() -> Result<Vec<String>, Box<dyn Error>> {
         }
     }
 
+    // freebl loader stub: routes AES_AEAD / ChaCha20Poly1305_* to libfreebl3.
+    println!("cargo:rustc-link-lib=static=freebl");
+
     Ok(flags)
 }
 

src/aead.rs

@@ -19,7 +19,7 @@ use crate::{
     secstatus_to_res,
 };
 
-#[cfg(not(feature = "disable-encryption"))]
+#[cfg(all(not(feature = "disable-encryption"), not(feature = "blapi")))]
 mod recprot {
     use std::{
         fmt,
@@ -238,6 +238,328 @@ mod recprot {
     }
 }
 
+#[cfg(all(not(feature = "disable-encryption"), feature = "blapi"))]
+mod recprot {
+    use std::{
+        fmt,
+        os::raw::{c_char, c_int, c_uint, c_ulong},
+        ptr::{null, null_mut},
+    };
+
+    use crate::{
+        Cipher, Error, Res, SymKey, Version,
+        constants::{TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256},
+        err::{sec::SEC_ERROR_BAD_DATA, secstatus_to_res},
+        freebl::{self, AesCtx, ChaCha20Ctx},
+        hp::SSL_HkdfExpandLabelWithMech,
+        p11::{CK_MECHANISM_TYPE, CKM_HKDF_DATA, PK11SymKey},
+    };
+
+    // Compile-time conversions of module constants to C types used in every
+    // freebl call — avoids repeated infallible try_from at each call site.
+    #[expect(clippy::cast_possible_truncation, reason = "NONCE_LEN = 12 and TAG_LEN = 16 both fit in u32")]
+    const NONCE_LEN_C: c_uint = super::NONCE_LEN as c_uint;
+    #[expect(clippy::cast_possible_truncation, reason = "NONCE_LEN = 12 and TAG_LEN = 16 both fit in u32")]
+    const TAG_LEN_C: c_uint = super::TAG_LEN as c_uint;
+    const NONCE_LEN_UL: c_ulong = super::NONCE_LEN as c_ulong;
+    const TAG_BITS_UL: c_ulong = (super::TAG_LEN * 8) as c_ulong;
+    #[expect(
+        clippy::cast_possible_truncation,
+        reason = "CK_GCM_MESSAGE_PARAMS is a small fixed struct"
+    )]
+    const GCM_PARAMS_LEN_C: c_uint = size_of::<freebl::CK_GCM_MESSAGE_PARAMS>() as c_uint;
+
+    enum CipherSpec {
+        Aes(c_uint),   // AES-GCM with this key length
+        ChaCha(c_uint), // ChaCha20-Poly1305 with this key length (always 32)
+    }
+
+    impl CipherSpec {
+        const fn key_len(&self) -> c_uint {
+            match self {
+                Self::Aes(n) | Self::ChaCha(n) => *n,
+            }
+        }
+    }
+
+    const fn cipher_spec(cipher: Cipher) -> Res<CipherSpec> {
+        match cipher {
+            TLS_AES_128_GCM_SHA256 => Ok(CipherSpec::Aes(16)),
+            TLS_AES_256_GCM_SHA384 => Ok(CipherSpec::Aes(32)),
+            TLS_CHACHA20_POLY1305_SHA256 => Ok(CipherSpec::ChaCha(32)),
+            _ => Err(Error::UnsupportedCipher),
+        }
+    }
+
+    fn expand_label(
+        version: Version,
+        cipher: Cipher,
+        secret: &SymKey,
+        label: &str,
+        key_len: c_uint,
+    ) -> Res<SymKey> {
+        let mut ptr: *mut PK11SymKey = null_mut();
+        unsafe {
+            SSL_HkdfExpandLabelWithMech(
+                version,
+                cipher,
+                **secret,
+                null(),
+                0,
+                label.as_ptr().cast::<c_char>(),
+                c_uint::try_from(label.len())?,
+                CK_MECHANISM_TYPE::from(CKM_HKDF_DATA),
+                key_len,
+                &raw mut ptr,
+            )
+        }?;
+        SymKey::from_ptr(ptr)
+    }
+
+    enum RecordCipher {
+        Aes {
+            ctx_encrypt: AesCtx,
+            ctx_decrypt: AesCtx,
+        },
+        ChaCha(ChaCha20Ctx),
+    }
+
+    /// Dispatch an AEAD operation to the appropriate freebl primitive.
+    ///
+    /// # Safety
+    ///
+    /// `output`, `tag`, and `input` must be valid for `output_max`, `TAG_LEN`,
+    /// and `input_len` bytes respectively.  `output` and `input` may overlap
+    /// (in-place); `tag` must not overlap the `output` region.
+    #[expect(clippy::too_many_arguments, reason = "Thin wrapper over two 10-argument C functions.")]
+    unsafe fn aead_op(
+        cipher: &RecordCipher,
+        encrypt: bool,
+        nonce: &mut [u8; super::NONCE_LEN],
+        aad: &[u8],
+        output: *mut u8,
+        output_max: c_uint,
+        tag: *mut u8,
+        input: *const u8,
+        input_len: c_uint,
+    ) -> Res<usize> {
+        let mut out_len: c_uint = 0;
+        let aad_len = c_uint::try_from(aad.len())?;
+        match cipher {
+            RecordCipher::Aes { ctx_encrypt, ctx_decrypt } => {
+                let ctx = if encrypt { ctx_encrypt } else { ctx_decrypt };
+                let mut params = freebl::CK_GCM_MESSAGE_PARAMS {
+                    pIv: nonce.as_mut_ptr(),
+                    ulIvLen: NONCE_LEN_UL,
+                    ulIvFixedBits: 0,
+                    ivGenerator: 0,
+                    pTag: tag,
+                    ulTagBits: TAG_BITS_UL,
+                };
+                secstatus_to_res(unsafe {
+                    freebl::AES_AEAD(
+                        **ctx,
+                        output,
+                        &raw mut out_len,
+                        output_max,
+                        input,
+                        input_len,
+                        std::ptr::from_mut(&mut params).cast(),
+                        GCM_PARAMS_LEN_C,
+                        aad.as_ptr(),
+                        aad_len,
+                    )
+                })?;
+            }
+            RecordCipher::ChaCha(ctx) => {
+                let f = if encrypt {
+                    freebl::ChaCha20Poly1305_Encrypt
+                } else {
+                    freebl::ChaCha20Poly1305_Decrypt
+                };
+                secstatus_to_res(unsafe {
+                    f(
+                        **ctx, output, &raw mut out_len, output_max,
+                        input, input_len, nonce.as_ptr(), NONCE_LEN_C,
+                        aad.as_ptr(), aad_len, tag,
+                    )
+                })?;
+            }
+        }
+        Ok(usize::try_from(out_len)?)
+    }
+
+    pub struct RecordProtection {
+        cipher: RecordCipher,
+        nonce_base: [u8; super::NONCE_LEN],
+    }
+
+    impl RecordProtection {
+        /// Create a new AEAD instance.
+        ///
+        /// # Errors
+        ///
+        /// Returns `Error` when the underlying crypto operations fail.
+        pub fn new(version: Version, cipher: Cipher, secret: &SymKey, prefix: &str) -> Res<Self> {
+            let spec = cipher_spec(cipher)?;
+            // Closure captures version/cipher/secret; binds result so key_bytes borrow stays live.
+            let derive = |suffix, len| {
+                expand_label(version, cipher, secret, &format!("{prefix}{suffix}"), len)
+            };
+            let key_sym = derive("key", spec.key_len())?;
+            let key_bytes = key_sym.key_data()?;
+
+            let nonce_base: [u8; super::NONCE_LEN] = derive("iv", NONCE_LEN_C)?
+                .key_data()?
+                .try_into()
+                .map_err(|_| Error::Internal)?;
+
+            let record_cipher = match spec {
+                CipherSpec::ChaCha(key_len) => RecordCipher::ChaCha(ChaCha20Ctx::from_ptr(unsafe {
+                    freebl::ChaCha20Poly1305_CreateContext(key_bytes.as_ptr(), key_len, TAG_LEN_C)
+                })?),
+                CipherSpec::Aes(key_len) => {
+                    let make_aes_ctx = |encrypt: c_int| unsafe {
+                        freebl::AES_CreateContext(key_bytes.as_ptr(), null(), freebl::NSS_AES_GCM, encrypt, key_len, 16)
+                    };
+                    RecordCipher::Aes {
+                        ctx_encrypt: AesCtx::from_ptr(make_aes_ctx(1))?,
+                        ctx_decrypt: AesCtx::from_ptr(make_aes_ctx(0))?,
+                    }
+                }
+            };
+
+            Ok(Self { cipher: record_cipher, nonce_base })
+        }
+
+        /// Get the expansion size (authentication tag length) for this AEAD.
+        #[must_use]
+        #[expect(clippy::unused_self)]
+        pub const fn expansion(&self) -> usize {
+            super::TAG_LEN
+        }
+
+        /// Encrypt plaintext with associated data.
+        ///
+        /// # Errors
+        ///
+        /// Returns `Error` when encryption fails.
+        pub fn encrypt<'a>(
+            &self,
+            count: u64,
+            aad: &[u8],
+            input: &[u8],
+            output: &'a mut [u8],
+        ) -> Res<&'a [u8]> {
+            if output.len() < input.len().checked_add(super::TAG_LEN).ok_or(Error::IntegerOverflow)? {
+                return Err(Error::from(SEC_ERROR_BAD_DATA));
+            }
+            let mut nonce = super::xor_nonce(&self.nonce_base, count);
+            let input_len = c_uint::try_from(input.len())?;
+            let out_len = unsafe {
+                aead_op(
+                    &self.cipher, true, &mut nonce, aad,
+                    output.as_mut_ptr(), input_len,
+                    output[input.len()..].as_mut_ptr(),
+                    input.as_ptr(), input_len,
+                )
+            }?;
+            debug_assert_eq!(out_len, input.len());
+            Ok(&output[..out_len + super::TAG_LEN])
+        }
+
+        /// Encrypt plaintext in place with associated data.
+        ///
+        /// # Errors
+        ///
+        /// Returns `Error` when encryption fails.
+        pub fn encrypt_in_place(&self, count: u64, aad: &[u8], data: &mut [u8]) -> Res<usize> {
+            if data.len() < self.expansion() {
+                return Err(Error::from(SEC_ERROR_BAD_DATA));
+            }
+            let pt_len = data.len() - self.expansion();
+            let mut nonce = super::xor_nonce(&self.nonce_base, count);
+            let data_ptr = data.as_mut_ptr();
+            let pt_len_c = c_uint::try_from(pt_len)?;
+            let out_len = unsafe {
+                aead_op(
+                    &self.cipher, true, &mut nonce, aad,
+                    data_ptr, pt_len_c,
+                    data_ptr.add(pt_len),
+                    data_ptr.cast_const(), pt_len_c,
+                )
+            }?;
+            debug_assert_eq!(out_len, pt_len);
+            Ok(data.len())
+        }
+
+        /// Decrypt ciphertext with associated data.
+        ///
+        /// # Errors
+        ///
+        /// Returns `Error` when decryption or authentication fails.
+        pub fn decrypt<'a>(
+            &self,
+            count: u64,
+            aad: &[u8],
+            input: &[u8],
+            output: &'a mut [u8],
+        ) -> Res<&'a [u8]> {
+            let ct_len = input
+                .len()
+                .checked_sub(super::TAG_LEN)
+                .ok_or_else(|| Error::from(SEC_ERROR_BAD_DATA))?;
+            if output.len() < ct_len {
+                return Err(Error::from(SEC_ERROR_BAD_DATA));
+            }
+            let mut tag = [0u8; super::TAG_LEN];
+            tag.copy_from_slice(&input[ct_len..ct_len + super::TAG_LEN]);
+            let mut nonce = super::xor_nonce(&self.nonce_base, count);
+            let out_len = unsafe {
+                aead_op(
+                    &self.cipher, false, &mut nonce, aad,
+                    output.as_mut_ptr(), c_uint::try_from(output.len())?,
+                    tag.as_mut_ptr(),
+                    input.as_ptr(), c_uint::try_from(ct_len)?,
+                )
+            }?;
+            Ok(&output[..out_len])
+        }
+
+        /// Decrypt ciphertext in place with associated data.
+        ///
+        /// # Errors
+        ///
+        /// Returns `Error` when decryption or authentication fails.
+        pub fn decrypt_in_place(&self, count: u64, aad: &[u8], data: &mut [u8]) -> Res<usize> {
+            let ct_len = data
+                .len()
+                .checked_sub(super::TAG_LEN)
+                .ok_or_else(|| Error::from(SEC_ERROR_BAD_DATA))?;
+            let mut tag = [0u8; super::TAG_LEN];
+            tag.copy_from_slice(&data[ct_len..ct_len + super::TAG_LEN]);
+            let mut nonce = super::xor_nonce(&self.nonce_base, count);
+            let data_ptr = data.as_mut_ptr();
+            let out_len = unsafe {
+                aead_op(
+                    &self.cipher, false, &mut nonce, aad,
+                    data_ptr, c_uint::try_from(data.len())?,
+                    tag.as_mut_ptr(),
+                    data_ptr.cast_const(), c_uint::try_from(ct_len)?,
+                )
+            }?;
+            debug_assert_eq!(out_len, ct_len);
+            Ok(out_len)
+        }
+    }
+
+    impl fmt::Debug for RecordProtection {
+        fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
+            write!(f, "[AEAD Context]")
+        }
+    }
+}
+
 #[cfg(feature = "disable-encryption")]
 mod recprot {
     use std::fmt;
@@ -464,6 +786,17 @@ const TAG_LEN: usize = 16;
 
 pub type SequenceNumber = u64;
 
+fn xor_nonce(base: &[u8; NONCE_LEN], count: SequenceNumber) -> [u8; NONCE_LEN] {
+    let mut nonce = *base;
+    for (n, &s) in nonce[NONCE_LEN - COUNTER_LEN..]
+        .iter_mut()
+        .zip(&count.to_be_bytes())
+    {
+        *n ^= s;
+    }
+    nonce
+}
+
 /// All the lengths used by `PK11_AEADOp` are signed.  This converts to that.
 fn c_int_len<T>(l: T) -> Res<c_int>
 where
@@ -513,12 +846,7 @@ impl Aead {
     }
 
     fn make_nonce(nonce: &mut [u8; NONCE_LEN], seq: SequenceNumber) {
-        for (n, &s) in nonce[NONCE_LEN - COUNTER_LEN..]
-            .iter_mut()
-            .zip(&seq.to_be_bytes())
-        {
-            *n ^= s;
-        }
+        *nonce = xor_nonce(nonce, seq);
     }
 
     pub fn import_key(algorithm: AeadAlgorithms, key: &[u8]) -> Result<SymKey, Error> {