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_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 set_session(&mut self, session: &SslSession) -> Result<(), ErrorStack>

Set a previously obtained session for resumption (SSL_set_session).

Call before the handshake.

Errors

Trait Implementations

impl Drop for Ssl

fn drop(&mut self)

Executes the destructor for this type.

impl Send for Ssl