Struct Ssl 

pub struct Ssl { /* private fields */ }

Per-connection TLS object (SSL*).

Has exclusive ownership over its state; no Clone. BIOs passed to Ssl::set_bio_duplex or Ssl::set_bio are owned by the Ssl thereafter.

Implementations

impl Ssl

pub fn set_bio_duplex(&mut self, bio: Bio)

Set a single duplex BIO for both reading and writing.

Transfers ownership of bio to the SSL object; do not use bio afterwards. Suitable for BIO_new_bio_pair endpoints.

When rbio == wbio (same pointer), OpenSSL only increments the reference count once, so the single reference in bio is correct.

Examples found in repository

examples/ssl.rs (line 63)

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 set_bio(&mut self, rbio: Bio, wbio: Bio)

Set separate read and write BIOs.

Transfers ownership of both rbio and wbio to the SSL object.

pub fn set_hostname(&mut self, hostname: &CStr) -> Result<(), ErrorStack>

Set the SNI hostname extension sent during the TLS handshake.

Call before Self::connect on client connections to enable SNI. hostname must be a NUL-terminated ASCII/UTF-8 hostname.

SSL_set_tlsext_host_name is a C macro expanding to SSL_ctrl(s, 55 /*SSL_CTRL_SET_TLSEXT_HOSTNAME*/, 0 /*TLSEXT_NAMETYPE_host_name*/, name).

Errors

Returns Err if the control call fails.

Examples found in repository

examples/ssl.rs (line 56)

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 set_connect_state(&mut self)

Set this SSL object to operate in client (connect) mode.

Required before calling Self::do_handshake if neither Self::connect nor Self::accept will be used.

Examples found in repository

examples/ssl.rs (line 55)

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 set_accept_state(&mut self)

Set this SSL object to operate in server (accept) mode.

Examples found in repository

examples/ssl.rs (line 57)

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 connect(&mut self) -> Result<(), SslIoError>

Initiate a client-side TLS handshake (SSL_connect).

Returns Ok(()) on success, SslIoError::WantRead / SslIoError::WantWrite when the operation must be retried after more data is available.

Errors

Examples found in repository

examples/ssl.rs (line 74)

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 accept(&mut self) -> Result<(), SslIoError>

Accept an incoming TLS connection (SSL_accept).

Returns Ok(()) on success, SslIoError::WantRead / SslIoError::WantWrite on non-blocking retry.

Errors

Examples found in repository

examples/ssl.rs (line 84)

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 do_handshake(&mut self) -> Result<(), SslIoError>

Drive the TLS handshake in either role (SSL_do_handshake).

The role must have been set via Self::set_connect_state or Self::set_accept_state (or implicitly by Self::connect / Self::accept).

Errors

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

Read decrypted application data (SSL_read_ex).

Returns the number of bytes written into buf on success.

Errors

Examples found in repository

examples/ssl.rs (line 116)

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 write(&mut self, buf: &[u8]) -> Result<usize, SslIoError>

Write application data (SSL_write_ex).

Returns the number of bytes consumed from buf on success.

Errors

Examples found in repository

examples/ssl.rs (line 112)

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 shutdown(&mut self) -> Result<ShutdownResult, ErrorStack>

Send a TLS close-notify alert (SSL_shutdown).

Returns ShutdownResult::Sent after the first shutdown stage and ShutdownResult::Complete after a bidirectional shutdown. Call twice on a non-blocking connection to complete the exchange.

Errors

Returns Err on a fatal error during shutdown.

pub fn peer_cert_chain(&self) -> Option<Vec<X509>>

Return the peer’s full certificate chain (leaf + intermediates), or None.

Each certificate in the returned Vec has its reference count independently incremented via X509_up_ref, so the certificates outlive self.

Returns None when:

• the handshake has not yet completed, or
• the peer did not present a certificate (e.g. a server without client-auth configured will see None for the client chain).

An empty Vec is returned if the stack exists but contains no elements (unusual in practice).

Note: this calls SSL_get_peer_cert_chain, which on the server side does not include the leaf certificate — only intermediates. On the client side the full chain including the server leaf is returned. Use Self::peer_certificate to obtain the leaf cert in all cases.

pub fn peer_certificate(&self) -> Option<X509>

Return the peer’s certificate, or None if unavailable.

The returned certificate has its reference count incremented, so it outlives self.

Examples found in repository

examples/ssl.rs (line 101)

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 get1_session(&self) -> Option<SslSession>

Get an owned reference to the current session (SSL_get1_session).

Returns None if no session is established. The session can be passed to Self::set_session on a new Ssl for resumption.

pub fn session(&self) -> Option<BorrowedSslSession<'_>>

Borrow the current session without incrementing the reference count (SSL_get_session).

Returns None if no session is associated with this connection (e.g. the handshake has not yet completed or session caching is disabled).

The returned BorrowedSslSession is valid for the lifetime of self and must not be retained beyond it. Use Self::get1_session if you need a session that outlives the connection.

Lifetimes

The borrow is tied to '_ (the lifetime of self): the SSL_SESSION* is owned by the SSL object and is invalidated when the Ssl is dropped or a new session is negotiated.

pub fn set_session(&mut self, session: &SslSession) -> Result<(), ErrorStack>

Set a previously obtained session for resumption (SSL_set_session).

Call before the handshake.

Errors

pub fn set_verify_hostname(&mut self, hostname: &str) -> Result<(), ErrorStack>

Override the expected server hostname for this connection’s certificate verification.

Use this when one SslCtx is shared across connections to different servers and per-connection hostname checking is needed. Wraps SSL_set1_host.

Errors

Returns Err if hostname contains a NUL byte or if SSL_set1_host fails.

Trait Implementations

impl Drop for Ssl

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Ssl