Struct Connection 

pub struct Connection { /* private fields */ }

A unified TLS or DTLS connection (client or server, any supported version).

Construct via Connection::client or Connection::server, passing a shared super::Config. The internal engine is picked from config.max_version.

Implementations

impl Connection

pub fn client(config: &Config) -> Result<Self, Error>

Build a client connection. Picks the engine from config.max_version.

Examples found in repository

examples/tls_loopback.rs (line 39)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

examples/tls_get.rs (line 33)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn server(config: &Config) -> Result<Self, Error>

Build a server connection. Picks the engine from config.max_version. Requires config.identity.is_some().

Examples found in repository

examples/tls_loopback.rs (line 29)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

pub fn handshake(&mut self) -> Result<HandshakeStatus, Error>

Drive the handshake forward. Returns the next HandshakeStatus.

Examples found in repository

examples/tls_get.rs (line 45)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn feed(&mut self, wire_in: &[u8]) -> Result<usize, Error>

Wire bytes from the peer into the engine. Returns the number of bytes consumed.

Examples found in repository

examples/tls_loopback.rs (line 45)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

examples/tls_get.rs (line 51)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn pop(&mut self) -> Result<Vec<u8>, Error>

Wire bytes the engine wants to send to the peer. For TLS, this is a contiguous stream slice; for DTLS, this is one datagram per call.

Examples found in repository

examples/tls_loopback.rs (line 43)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

examples/tls_get.rs (line 41)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn send(&mut self, app: &[u8]) -> Result<(), Error>

App bytes into the engine (post-handshake).

Examples found in repository

examples/tls_loopback.rs (line 59)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

examples/tls_get.rs (line 61)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn recv(&mut self) -> Result<Vec<u8>, Error>

App bytes out (post-handshake).

Examples found in repository

examples/tls_loopback.rs (line 64)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

examples/tls_get.rs (line 74)

fn main() {
    let insecure = std::env::args().any(|a| a == "--insecure");

    let roots = if insecure {
        RootCertStore::new()
    } else {
        load_system_roots()
    };
    let cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name(HOST)
        .verify_certificates(!insecure)
        .build();
    let mut conn = Connection::client(&cfg).expect("client config");

    let mut sock = TcpStream::connect((HOST, 443)).expect("TCP connect");
    sock.set_read_timeout(Some(Duration::from_secs(5))).unwrap();

    // Drive the handshake to completion.
    let mut read_buf = [0u8; 8192];
    loop {
        let out = conn.pop().unwrap_or_default();
        if !out.is_empty() {
            sock.write_all(&out).unwrap();
        }
        match conn.handshake().unwrap() {
            HandshakeStatus::Complete => break,
            HandshakeStatus::WantWrite => continue,
            HandshakeStatus::WantRead => {
                let n = sock.read(&mut read_buf).expect("read");
                assert!(n > 0, "peer closed during handshake");
                conn.feed(&read_buf[..n]).expect("feed");
            }
        }
    }
    eprintln!(
        "TLS 1.3 handshake with {HOST} complete (certificate {}verified)",
        if insecure { "NOT " } else { "" }
    );

    let request = "GET / HTTP/1.1\r\nHost: example.org\r\n\r\n";
    conn.send(request.as_bytes()).unwrap();
    let out = conn.pop().unwrap_or_default();
    sock.write_all(&out).unwrap();
    sock.flush().unwrap();

    let mut response = Vec::new();
    loop {
        match sock.read(&mut read_buf) {
            Ok(0) => break,
            Ok(n) => {
                if conn.feed(&read_buf[..n]).is_err() {
                    break;
                }
                let plain = conn.recv().unwrap_or_default();
                response.extend_from_slice(&plain);
                if response.len() > 16 * 1024 {
                    break;
                }
            }
            Err(e)
                if e.kind() == std::io::ErrorKind::WouldBlock
                    || e.kind() == std::io::ErrorKind::TimedOut =>
            {
                break;
            }
            Err(e) => {
                eprintln!("read error: {e}");
                break;
            }
        }
    }

    let text = String::from_utf8_lossy(&response);
    println!("--- {} bytes received ---", response.len());
    for line in text.lines().take(15) {
        println!("{line}");
    }
}

pub fn close(&mut self) -> Result<(), Error>

Close the connection, emitting a close_notify alert if the engine supports it.

pub fn is_handshake_complete(&self) -> bool

True once the handshake has completed.

Examples found in repository

examples/tls_loopback.rs (line 55)

fn main() {
    // --- Server setup: a self-signed certificate for "example.test". ---
    let signing_key = RsaPrivateKey::<32>::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let name = DistinguishedName::common_name("example.test");
    let validity = Validity::new(
        Time::utc(2024, 1, 1, 0, 0, 0),
        Time::utc(2034, 1, 1, 0, 0, 0),
    );
    let cert = Certificate::self_signed(&signing_key, &name, &validity, 1, false).unwrap();
    let cert_der = cert.to_der().to_vec();

    let server_key = BoxedRsaPrivateKey::from_pkcs1_pem(SERVER_KEY_PEM).unwrap();
    let server_cfg = Config::builder()
        .tls_only()
        .identity(vec![cert_der.clone()], SigningKey::Rsa(server_key))
        .build();
    let mut server = Connection::server(&server_cfg).expect("server config");

    // --- Client setup: trust the server's certificate. ---
    let mut roots = RootCertStore::new();
    roots.add_der(cert_der).unwrap();
    let client_cfg = Config::builder()
        .tls_only()
        .roots(roots)
        .server_name("example.test")
        .build();
    let mut client = Connection::client(&client_cfg).expect("client config");

    // --- Drive the handshake by shuttling records between the two ends. ---
    for _ in 0..16 {
        let to_server = client.pop().unwrap_or_default();
        if !to_server.is_empty() {
            server.feed(&to_server).unwrap();
        }
        let to_client = server.pop().unwrap_or_default();
        if !to_client.is_empty() {
            client.feed(&to_client).unwrap();
        }
        if to_server.is_empty() && to_client.is_empty() {
            break;
        }
    }
    assert!(client.is_handshake_complete() && server.is_handshake_complete());
    println!("handshake complete");

    // --- Application data: client -> server -> client. ---
    client.send(b"GET / HTTP/1.0").unwrap();
    let req = client.pop().unwrap_or_default();
    server.feed(&req).unwrap();
    println!(
        "server received: {:?}",
        String::from_utf8_lossy(&server.recv().unwrap_or_default())
    );

    server.send(b"HTTP/1.0 200 OK").unwrap();
    let resp = server.pop().unwrap_or_default();
    client.feed(&resp).unwrap();
    println!(
        "client received: {:?}",
        String::from_utf8_lossy(&client.recv().unwrap_or_default())
    );
}

pub fn negotiated_version(&self) -> Option<ProtocolVersion>

The negotiated wire version, if the handshake has progressed enough to determine it.

pub fn negotiated_cipher_suite(&self) -> Option<u16>

IANA cipher-suite identifier of the negotiated suite. None until the handshake has advanced far enough to fix the suite (ServerHello processed on the client, ClientHello processed on the server).

pub fn negotiated_cipher_suite_name(&self) -> Option<&'static str>

The IANA name of the negotiated cipher suite, or None until the suite is fixed. Returns the well-known strings for the suites purecrypto negotiates (TLS 1.3 trio + the TLS 1.2 ECDHE-AEAD set); unknown codes resolve to "UNKNOWN".

pub fn alpn_selected(&self) -> Option<&[u8]>

The negotiated ALPN protocol, if any.

pub fn peer_server_name(&self) -> Option<&str>

Server-side: the SNI host_name the client offered in the ClientHello server_name extension (RFC 6066 §3). None for client engines, for DTLS engines (no SNI plumbing yet), or when the peer omitted the extension. Available once the ClientHello has been processed.

pub fn peer_certificates(&self) -> &[Vec<u8>]

The peer’s certificate chain (leaf first, DER).

pub fn next_timeout(&self) -> Option<Duration>

DTLS: next retransmit timeout. None on TLS variants.

pub fn on_timeout(&mut self, now: Duration)

DTLS: notify the engine that the retransmit deadline has elapsed. No-op on TLS variants.