net::tls - Cryo

A thin, safe binding over the system OpenSSL — not a reimplementation. TlsConnector (client) and TlsAcceptor (server) mint TlsStreams, which implement AsyncTransport exactly as TcpStream does, so the HTTP and WebSocket layers run over them unchanged. That is the whole point of routing TLS through the same seam as plaintext TCP.

public module net::tls::stream;
public module net::tls::context;
public module net::tls::future;

File	What it holds	Import
`context`	`TlsConnector`, `TlsAcceptor` — the `SSL_CTX` owners	`import std::net::tls::context;`
`stream`	`TlsStream`, `AlpnProtocol`	`import std::net::tls::stream;`
`future`	`TlsHandshake`, `TlsRead`, `TlsWrite`, `TlsIo`	`import std::net::tls::future;`

import std::net::tls;

mut connector: TlsConnector = TlsConnector::new()?;
mut tls: TlsStream = await connector.connect(tcp, host)?;

Any binary using this module must add ssl and crypto to link_libs in its cryoconfig. See ffi::openssl. Nothing here is referenced unless net::tls is used, so non-TLS binaries link without OpenSSL.

For one-shot HTTPS requests that tie resolution, dialling, TLS, and HTTP together, see net::https.

public function name() { ... }
public:

Visible to any module that imports this one - the default for top-level items and for struct fields, so it is mostly written to be explicit. public: opens a visibility block that groups the members after it.

language reference

public module collections::array;

In a directory's _module.cryo aggregator, lists a submodule and whether it is public. Importing the directory's namespace sees only the modules declared public here.

language reference

namespace std::net;

net: network primitives + HTTP.

module page

namespace std::net::tls;

net::tls: TLS over TCP via system OpenSSL.

module page

namespace std::net::tls::stream;

TlsStream: an encrypted byte stream over a TcpStream.

module page

namespace std::net::tls::context;

TLS contexts: TlsConnector (client) and TlsAcceptor (server).

module page

namespace std::net::tls::future;

Async TLS: the futures that drive OpenSSL on a NON-BLOCKING socket.

module page

import a::b;
import a::b::{ X, Y };
import a::b as c;
import a::b::*;

Brings a module, or selected items from it, into scope. One path per declaration: use the brace form for several items, as to alias, and * for everything public (prefer the brace form; wildcards invite name collisions).

language reference

namespace std;

std: the Cryo standard library.

module page

mut name: Type = value;

A mutable binding, reassignable after declaration - mutability is opt-in, const is the default. At module level it declares mutable global state. Before & it marks an exclusive reference or receiver instead.

language reference

mut connector: TlsConnector

type struct TlsConnector {
    ctx: void*;
    verify: boolean;
}

std::net::tls::context

static TlsConnector::new() -> Result<TlsConnector, IoError>

New client context with the system trust store loaded and peer verification on by default.

std::net::tls::context

value?

Error propagation. On a Result<T, E> it yields the T of an Ok and otherwise returns the Err(e) from the enclosing function unchanged; on an Option<T> it yields the T of a Some or returns None. The enclosing function must return a matching Result / Option.

language reference

mut tls: TlsStream

type struct TlsStream {
    ssl: void*;
    inner: TcpStream;
}

std::net::tls::stream

await future

Suspends the enclosing async body until the operand - which must implement Future - completes, and evaluates to its output. A prefix operator allowed anywhere an expression is (conditions, arms, guards), but only inside async code.

language reference

mut connector: TlsConnector

declared in this snippet

async TlsConnector::connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsStream, IoError>

Wrap an established TcpStream in TLS, performing the client handshake with SNI set to hostname (also the name verified against the peer certificate when verification is on). Consumes the TcpStream; on failure it is closed before returning.

std::net::tls::context

type struct TlsAcceptor {
    ctx: void*;
}

std::net::tls::context

type trait AsyncTransport {
    async read_into(mut &this, buf: Array<u8>) -> Transfer;
    async write_from(mut &this, buf: Array<u8>) -> Transfer;
}

One raw, unbuffered async byte channel: what BufStream<S> needs of a transport, and nothing more.

std::io::traits

type struct TcpStream {
    fd: i32;
}

std::net::socket::tcp

type enum AlpnProtocol {
    None;
    Http11;
    H2;
}

Application-layer protocol negotiated during the handshake (ALPN).

std::net::tls::stream

type struct TlsHandshake {
    tls: TlsStream;
    is_client: boolean;
    verify: boolean;
    rt: Reactor*;
    armed: u32;
}

Drive a TLS handshake to completion without blocking. SSL_connect (client) or SSL_accept (server) is re-issued on every poll — which is exactly what OpenSSL wants after a WANT_* — until it reports success or a real failure.

std::net::tls::future

type struct TlsRead {
    tls: TlsStream;
    buf: Array<u8>;
    rt: Reactor*;
    armed: u32;
}

Read decrypted bytes as soon as the connection has some. Completes with the byte count — 0 means the peer sent close_notify, the TLS equivalent of EOF — or the error that ended it.

std::net::tls::future

type struct TlsWrite {
    tls: TlsStream;
    buf: Array<u8>;
    rt: Reactor*;
    armed: u32;
}

Write plaintext as soon as the connection has room for the resulting record. Completes with the number of bytes accepted, which may be fewer than asked for — a caller with more to send starts another write for the remainder, which is why the buffer comes back untouched.

std::net::tls::future

type struct TlsIo {
    tls: TlsStream;
    buf: Array<u8>;
    result: Result<u64, IoError>;
}

The outcome of an async TLS read or write: the stream and the buffer handed back, plus how many bytes moved (or why none did).

std::net::tls::future