native_ossl/

bio.rs

//! BIO wrappers — `MemBio`, `MemBioBuf<'a>`, `Bio`.
//!
//! BIOs are OpenSSL's generic I/O abstraction.  This module exposes three types:
//!
//! - [`MemBio`] — a writable, growable in-memory BIO (`BIO_s_mem()`).  Used for
//!   encoding output (PEM, DER).  Call `data()` after writing to read the result
//!   as a `&[u8]` slice without copying.
//!
//! - [`MemBioBuf<'a>`] — a read-only view of a caller-supplied slice
//!   (`BIO_new_mem_buf()`).  Zero-copy input path for PEM parsing.
//!
//! - [`Bio`] — shared ownership wrapper around a raw `BIO*`.  Used when OpenSSL
//!   needs a `BIO` that outlives the immediate call (e.g. TLS `SSL_set_bio`).

use crate::error::ErrorStack;
use native_ossl_sys as sys;
use std::marker::PhantomData;
use std::ptr;

// ── MemBio — writable in-memory BIO ──────────────────────────────────────────

/// A writable, growable in-memory BIO.
///
/// Data written to this BIO accumulates in an internal buffer managed by
/// OpenSSL.  After writing, `data()` returns a borrowed slice without copying.
pub struct MemBio {
    ptr: *mut sys::BIO,
}

impl MemBio {
    /// Create a new empty writable `BIO_s_mem()` BIO.
    ///
    /// # Errors
    ///
    /// Returns `Err` if OpenSSL cannot allocate the BIO.
    pub fn new() -> Result<Self, ErrorStack> {
        let method = unsafe { sys::BIO_s_mem() };
        if method.is_null() {
            return Err(ErrorStack::drain());
        }
        let ptr = unsafe { sys::BIO_new(method) };
        if ptr.is_null() {
            return Err(ErrorStack::drain());
        }
        Ok(MemBio { ptr })
    }

    /// Write bytes into the BIO's internal buffer.
    ///
    /// # Errors
    ///
    /// Returns `Err` if the write fails.
    pub fn write(&mut self, data: &[u8]) -> Result<(), ErrorStack> {
        let mut written: usize = 0;
        let rc = unsafe {
            sys::BIO_write_ex(
                self.ptr,
                data.as_ptr().cast(),
                data.len(),
                std::ptr::addr_of_mut!(written),
            )
        };
        if rc != 1 || written != data.len() {
            return Err(ErrorStack::drain());
        }
        Ok(())
    }

    /// Borrow the current contents of the BIO's buffer as a `&[u8]`.
    ///
    /// The slice is valid until the next write operation or until `self` is dropped.
    /// This is a zero-copy view — no allocation occurs.
    #[must_use]
    pub fn data(&self) -> &[u8] {
        let mut ptr: *mut std::os::raw::c_char = ptr::null_mut();
        // BIO_get_mem_data is the C macro equivalent of:
        //   BIO_ctrl(b, BIO_CTRL_INFO, 0, (char**)(pp))
        // BIO_CTRL_INFO = 3.
        let len = unsafe {
            sys::BIO_ctrl(
                self.ptr,
                3, // BIO_CTRL_INFO
                0,
                (&raw mut ptr).cast::<std::os::raw::c_void>(),
            )
        };
        if len <= 0 || ptr.is_null() {
            return &[];
        }
        let n = usize::try_from(len).unwrap_or(0);
        unsafe { std::slice::from_raw_parts(ptr.cast::<u8>(), n) }
    }

    /// Move the buffer contents into a freshly allocated `Vec<u8>`.
    ///
    /// Prefer `data()` when a borrow suffices.
    #[must_use]
    pub fn into_vec(self) -> Vec<u8> {
        self.data().to_vec()
    }

    /// Return the raw `BIO*` pointer.
    ///
    /// The pointer is valid for the lifetime of `self`.
    #[must_use]
    #[allow(dead_code)] // used by x509/ssl modules added in Phase 7-8
    pub(crate) fn as_ptr(&mut self) -> *mut sys::BIO {
        self.ptr
    }
}

impl Drop for MemBio {
    fn drop(&mut self) {
        unsafe { sys::BIO_free_all(self.ptr) };
    }
}

// SAFETY: BIO_s_mem() BIOs do not reference external state.
unsafe impl Send for MemBio {}

// ── MemBioBuf — read-only view into a caller slice ───────────────────────────

/// A read-only BIO wrapping a borrowed byte slice (`BIO_new_mem_buf()`).
///
/// Zero-copy: no data is copied from the slice.  The `BIO*` pointer reads
/// directly from the caller's memory.  The lifetime `'a` ties the BIO to the
/// source slice.
pub struct MemBioBuf<'a> {
    ptr: *mut sys::BIO,
    _data: PhantomData<&'a [u8]>,
}

impl<'a> MemBioBuf<'a> {
    /// Create a read-only BIO backed by `data`.
    ///
    /// OpenSSL reads from `data` directly; no copy occurs.
    ///
    /// # Errors
    ///
    /// Returns `Err` if OpenSSL cannot allocate the BIO wrapper, or if
    /// `data.len()` exceeds `i32::MAX`.
    pub fn new(data: &'a [u8]) -> Result<Self, ErrorStack> {
        // BIO_new_mem_buf reads from the caller's slice directly.
        // -1 means use data.len() (NUL-terminated string convention is not used here
        // because we pass the explicit length).
        let len = i32::try_from(data.len()).map_err(|_| ErrorStack::drain())?;
        let ptr = unsafe { sys::BIO_new_mem_buf(data.as_ptr().cast(), len) };
        if ptr.is_null() {
            return Err(ErrorStack::drain());
        }
        Ok(MemBioBuf {
            ptr,
            _data: PhantomData,
        })
    }

    /// Return the raw `BIO*` pointer.
    #[must_use]
    #[allow(dead_code)] // used by x509/ssl modules added in Phase 7-8
    pub(crate) fn as_ptr(&self) -> *mut sys::BIO {
        self.ptr
    }
}

impl Drop for MemBioBuf<'_> {
    fn drop(&mut self) {
        unsafe { sys::BIO_free(self.ptr) };
    }
}

// SAFETY: the slice reference `'a` bounds the BIO's use; it cannot outlive the slice.
unsafe impl Send for MemBioBuf<'_> {}

// ── Bio — shared ownership BIO ────────────────────────────────────────────────

/// Shared ownership wrapper around a `BIO*`.
///
/// Used where OpenSSL takes ownership of a BIO (e.g. `SSL_set_bio`) or where
/// the same BIO must be reachable from multiple Rust values.  Implemented with
/// `BIO_up_ref` / `BIO_free`.
pub struct Bio {
    ptr: *mut sys::BIO,
}

impl Bio {
    /// Create a linked in-memory BIO pair suitable for in-process TLS.
    ///
    /// Returns `(bio1, bio2)` where data written to `bio1` is readable from
    /// `bio2` and vice-versa.  Pass each half to [`crate::ssl::Ssl::set_bio_duplex`] on
    /// the client and server `Ssl` objects respectively.
    ///
    /// # Errors
    ///
    /// Returns `Err` if OpenSSL fails to allocate the pair.
    pub fn new_pair() -> Result<(Self, Self), crate::error::ErrorStack> {
        let mut b1: *mut sys::BIO = std::ptr::null_mut();
        let mut b2: *mut sys::BIO = std::ptr::null_mut();
        let rc = unsafe {
            sys::BIO_new_bio_pair(
                std::ptr::addr_of_mut!(b1),
                0,
                std::ptr::addr_of_mut!(b2),
                0,
            )
        };
        if rc != 1 {
            return Err(crate::error::ErrorStack::drain());
        }
        Ok((Bio { ptr: b1 }, Bio { ptr: b2 }))
    }

    /// Wrap a raw `BIO*` transferring ownership to this `Bio`.
    ///
    /// # Safety
    ///
    /// `ptr` must be a valid, non-null `BIO*` that the caller is giving up ownership of.
    #[must_use]
    #[allow(dead_code)] // used by ssl tests
    pub(crate) unsafe fn from_ptr_owned(ptr: *mut sys::BIO) -> Self {
        Bio { ptr }
    }

    /// Return the raw `BIO*` pointer.  Valid for the lifetime of `self`.
    #[must_use]
    pub(crate) fn as_ptr(&self) -> *mut sys::BIO {
        self.ptr
    }
}

impl Clone for Bio {
    fn clone(&self) -> Self {
        unsafe { sys::BIO_up_ref(self.ptr) };
        Bio { ptr: self.ptr }
    }
}

impl Drop for Bio {
    fn drop(&mut self) {
        unsafe { sys::BIO_free(self.ptr) };
    }
}

// SAFETY: `BIO_up_ref` / `BIO_free` are thread-safe for memory BIOs.
unsafe impl Send for Bio {}
unsafe impl Sync for Bio {}

// ── Tests ─────────────────────────────────────────────────────────────────────

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn mem_bio_write_and_data() {
        let mut bio = MemBio::new().unwrap();
        bio.write(b"hello").unwrap();
        bio.write(b" world").unwrap();
        assert_eq!(bio.data(), b"hello world");
    }

    #[test]
    fn mem_bio_empty() {
        let bio = MemBio::new().unwrap();
        assert_eq!(bio.data(), b"");
    }

    #[test]
    fn mem_bio_buf_zero_copy() {
        let source = b"PEM data goes here";
        let bio = MemBioBuf::new(source).unwrap();
        // Verify the BIO's internal read pointer equals the source slice pointer.
        let mut char_ptr: *mut std::os::raw::c_char = ptr::null_mut();
        // BIO_get_mem_data via BIO_ctrl(BIO_CTRL_INFO=3).
        let len = unsafe {
            sys::BIO_ctrl(
                bio.as_ptr(),
                3, // BIO_CTRL_INFO
                0,
                (&raw mut char_ptr).cast::<std::os::raw::c_void>(),
            )
        };
        assert_eq!(usize::try_from(len).unwrap(), source.len());
        // The data pointer must be the same as the source slice's pointer.
        assert_eq!(char_ptr.cast::<u8>().cast_const(), source.as_ptr());
    }

    #[test]
    fn bio_clone_shares_object() {
        // Create a MemBio and wrap its underlying pointer in a Bio to test Clone.
        let mut mem = MemBio::new().unwrap();
        mem.write(b"test").unwrap();

        // Build a Bio using the MemBio's pointer (up_ref first to share ownership).
        let raw = mem.as_ptr();
        unsafe { sys::BIO_up_ref(raw) };
        let bio = unsafe { Bio::from_ptr_owned(raw) };
        let bio2 = bio.clone();

        // Both should point to the same BIO object.
        assert_eq!(bio.as_ptr(), bio2.as_ptr());
    }
}