Struct Bio 

pub struct Bio { /* private fields */ }

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.

Implementations

impl Bio

pub fn new_pair() -> Result<(Self, Self), ErrorStack>

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.

Examples found in repository

examples/ssl.rs (line 62)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // ── Key pair and self-signed certificate ───────────────────────────────────

    let mut kgen = KeygenCtx::new(c"ED25519")?;
    let priv_key = kgen.generate()?;
    let pub_key = native_ossl::pkey::Pkey::<native_ossl::pkey::Public>::from(priv_key.clone());

    let mut name = X509NameOwned::new()?;
    name.add_entry_by_txt(c"CN", b"localhost")?;

    let cert = X509Builder::new()?
        .set_version(2)?
        .set_serial_number(1)?
        .set_not_before_offset(0)?
        .set_not_after_offset(86400)?
        .set_subject_name(&name)?
        .set_issuer_name(&name)?
        .set_public_key(&pub_key)?
        .sign(&priv_key, None)?
        .build();

    // ── Server context ─────────────────────────────────────────────────────────

    let server_ctx = SslCtx::new_server()?;
    server_ctx.set_min_proto_version(TlsVersion::Tls13)?;
    server_ctx.use_certificate(&cert)?;
    server_ctx.use_private_key(&priv_key)?;
    server_ctx.check_private_key()?;

    // ── Client context ─────────────────────────────────────────────────────────

    let client_ctx = SslCtx::new_client()?;
    client_ctx.set_min_proto_version(TlsVersion::Tls13)?;
    // Skip certificate verification for this self-signed example.
    client_ctx.set_verify(SslVerifyMode::NONE);

    // ── SSL objects ────────────────────────────────────────────────────────────

    let mut client = client_ctx.new_ssl()?;
    let mut server = server_ctx.new_ssl()?;

    client.set_connect_state();
    client.set_hostname(c"localhost")?;
    server.set_accept_state();

    // ── In-process BIO pair ────────────────────────────────────────────────────
    // Data written to client_bio is readable from server_bio and vice-versa.

    let (client_bio, server_bio) = Bio::new_pair()?;
    client.set_bio_duplex(client_bio);
    server.set_bio_duplex(server_bio);

    // ── Drive the handshake ────────────────────────────────────────────────────
    // Alternate between client and server until both report success.

    let mut client_done = false;
    let mut server_done = false;

    for step in 0..20 {
        if !client_done {
            match client.connect() {
                Ok(()) => {
                    client_done = true;
                    println!("Client handshake done at step {step}");
                }
                Err(SslIoError::WantRead | SslIoError::WantWrite) => {}
                Err(e) => return Err(format!("client error: {e}").into()),
            }
        }
        if !server_done {
            match server.accept() {
                Ok(()) => {
                    server_done = true;
                    println!("Server handshake done at step {step}");
                }
                Err(SslIoError::WantRead | SslIoError::WantWrite) => {}
                Err(e) => return Err(format!("server error: {e}").into()),
            }
        }
        if client_done && server_done {
            break;
        }
    }
    assert!(client_done && server_done, "handshake did not complete");

    // ── Inspect the peer certificate on the client ─────────────────────────────

    if let Some(peer_cert) = client.peer_certificate() {
        if let Some(subject) = peer_cert.subject_name().to_string() {
            println!("Server cert subject: {subject}");
        }
    }

    // ── Application data exchange ──────────────────────────────────────────────

    let request = b"GET / HTTP/1.0\r\n\r\n";
    let response = b"HTTP/1.0 200 OK\r\n\r\nHello, TLS!";

    let written = client.write(request)?;
    assert_eq!(written, request.len());

    let mut rbuf = [0u8; 64];
    let n = server.read(&mut rbuf)?;
    assert_eq!(&rbuf[..n], request);
    println!("Server received: {:?}", std::str::from_utf8(&rbuf[..n])?);

    let written = server.write(response)?;
    assert_eq!(written, response.len());

    let n = client.read(&mut rbuf)?;
    assert_eq!(&rbuf[..n], response);
    println!("Client received: {:?}", std::str::from_utf8(&rbuf[..n])?);

    println!("In-process TLS 1.3 round-trip: OK");

    Ok(())
}

pub fn read(&mut self, buf: &mut [u8]) -> Result<usize, ErrorStack>

Read bytes from the BIO into buf.

Returns the number of bytes actually read, which may be less than buf.len() if fewer bytes are available.

Errors

Returns Err on I/O error or EOF (when BIO_read returns -1).

pub fn read_ex(&mut self, buf: &mut [u8]) -> Result<usize, ErrorStack>

Read bytes from the BIO, reporting the exact number of bytes read.

On success returns the number of bytes placed into buf.

Errors

Returns Err if BIO_read_ex reports failure (returns 0).

pub fn write(&mut self, buf: &[u8]) -> Result<usize, ErrorStack>

Write buf into the BIO.

Returns the number of bytes actually written.

Errors

Returns Err on I/O error (when BIO_write returns -1).

pub fn push(self, next: Bio) -> Bio

Append next after self in the BIO chain.

Ownership of next is transferred into the chain; it must not be freed separately. Returns self with the chain extended.

Corresponds to BIO_push(self, next).

pub fn pop(&mut self) -> Option<Bio>

Remove self from its chain and return the rest of the chain.

After this call self is a standalone BIO. Returns None if self was the only (or last) element in the chain.

Corresponds to BIO_pop(self).

pub fn next(&self) -> Option<BorrowedBio<'_>>

Return a borrowed view of the next BIO in the chain without consuming self.

The returned BorrowedBio is valid for the lifetime of self and does not free the underlying pointer when dropped.

Returns None if self is the last (or only) BIO in the chain.

Corresponds to BIO_next(self).

pub fn pending(&self) -> usize

Return the number of bytes available for reading from the BIO.

Corresponds to the BIO_pending C macro, implemented via BIO_ctrl(b, BIO_CTRL_PENDING, 0, NULL).

For a mem BIO this is the number of unread bytes in the buffer. For other BIO types the value is type-specific.

pub fn wpending(&self) -> usize

Return the number of bytes still to be written (pending in the write buffer).

Corresponds to the BIO_wpending C macro, implemented via BIO_ctrl(b, BIO_CTRL_WPENDING, 0, NULL).

For most BIO types this is 0 (writes are synchronous). For filter BIOs it reflects bytes buffered but not yet flushed downstream.

pub fn find_type(&self, bio_type: c_int) -> Option<BorrowedBio<'_>>

Search the chain for the first BIO of the given bio_type.

bio_type is one of the BIO_TYPE_* integer constants from OpenSSL (e.g. BIO_TYPE_MEM = 8, BIO_TYPE_BIO = 19).

Returns a borrowed view of the matching BIO, or None if none is found.

Corresponds to BIO_find_type(self, bio_type).

Errors

Returns None if no BIO of the requested type exists in the chain.

Trait Implementations

impl Clone for Bio

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Drop for Bio

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Bio

impl Sync for Bio