context
import std::net::tls::context; · source
Each of the two context types owns an OpenSSL SSL_CTX and mints a TlsStream per connection from it. connect and accept are the async entry points: hand over a connected TcpStream and get back a TlsStream once the handshake completes. start_connect and start_accept hand back the TlsHandshake future instead, for callers composing it by hand — under a Futures::timeout, say.
Types
TlsConnector
type struct TlsConnector {
ctx: void*;
verify: boolean;
static new() -> Result<TlsConnector, IoError>;
danger_accept_invalid_certs(mut this) -> TlsConnector;
with_alpn_h2(mut this) -> TlsConnector;
async connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsStream, IoError>;
start_connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsHandshake, IoError>;
}The client side: the TLS client method, with certificate verification against the system store on by default. danger_accept_invalid_certs() is named to be conspicuous at the call site, because it disables verification. with_alpn_h2() offers h2 then http/1.1 during the handshake, and negotiated_alpn() on the resulting stream reports which one the server picked — that is how a client decides between net::http and net::http2 on a single connection. Both are fluent and consume the connector.
Properties
| Property | Type |
|---|---|
ctx | void* |
verify | boolean |
Constructors
static new() -> Result<TlsConnector, IoError>;
static new() -> Result<TlsConnector, IoError>;New client context with the system trust store loaded and peer verification on by default.
Methods
danger_accept_invalid_certs(mut this) -> TlsConnector;
danger_accept_invalid_certs(mut this) -> TlsConnector;Disable certificate + hostname verification. Named to be ugly on purpose: only for self-signed test servers or pinned-out-of-band peers. Fluent: returns the connector.
with_alpn_h2(mut this) -> TlsConnector;
with_alpn_h2(mut this) -> TlsConnector;Advertise HTTP/2 (and HTTP/1.1) via ALPN. Read the negotiated result back with TlsStream::negotiated_alpn. Fluent.
async connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsStream, IoError>;
async 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.
start_connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsHandshake, IoError>;
start_connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsHandshake, IoError>;Set the socket non-blocking and mint the SSL* with the SNI and verification wiring, handing back the future that drives the handshake.
TlsAcceptor
type struct TlsAcceptor {
ctx: void*;
static new(cert_path: Str, key_path: Str) -> Result<TlsAcceptor, IoError>;
async accept(&this, stream: TcpStream) -> Result<TlsStream, IoError>;
start_accept(&this, stream: TcpStream) -> Result<TlsHandshake, IoError>;
}The server side: the TLS server method loaded with the PEM certificate chain and private key at cert_path and key_path. accept runs the server half of the handshake on an accepted TcpStream.
Because SSL_new takes a reference on the context, a stream outlives its connector or acceptor regardless of which drops first. Both close their context through an inherent drop.
Properties
| Property | Type |
|---|---|
ctx | void* |
Constructors
static new(cert_path: Str, key_path: Str) -> Result<TlsAcceptor, IoError>;
static new(cert_path: Str, key_path: Str) -> Result<TlsAcceptor, IoError>;New server context from a PEM certificate chain and private key (paths on disk). Fails InvalidInput if either file is missing or the key doesn't match the certificate.
Methods
async accept(&this, stream: TcpStream) -> Result<TlsStream, IoError>;
async accept(&this, stream: TcpStream) -> Result<TlsStream, IoError>;Complete the server handshake over an accepted TcpStream. Consumes it; closes it on failure.
start_accept(&this, stream: TcpStream) -> Result<TlsHandshake, IoError>;
start_accept(&this, stream: TcpStream) -> Result<TlsHandshake, IoError>;Mint the SSL* and hand back the handshake future, the server-side mirror of start_connect. A socket handed over by TcpAccept is already non-blocking, but it is set here rather than assumed.
Constants
const ALPN_H2_HTTP11_LEN: u32 = 11;type struct Name { ... }
type enum Name { ... }
type trait Name { ... }
type union Name { ... }Begins a type declaration; the keyword that follows says which kind. On its own, type Name = Existing; declares an alias.
type struct Name {
field: Type;
method(&this) -> Ret { ... }
}A value type with named fields and optional methods. Structs live on the stack and are passed by value. Fields are public by default and may carry = default values; methods take their receiver as &this, mut &this, or this.
type struct TlsConnector {
ctx: void*;
verify: boolean;
}TlsConnector.ctx: void*TlsConnector.verify: booleanstatic name(param: Type) -> Ret { ... }A method that belongs to the type rather than an instance, called as Type::name(..). For structs, static new(..) returning a struct literal is the idiomatic constructor.
static TlsConnector::new() -> Result<TlsConnector, IoError>New client context with the system trust store loaded and peer verification on by default.
type struct TlsConnector {
ctx: void*;
verify: boolean;
}type struct IoError {
kind: IoErrorKind;
os_code: i32;
}TlsConnector::danger_accept_invalid_certs(mut this) -> TlsConnectorDisable certificate + hostname verification. Named to be ugly on purpose: only for self-signed test servers or pinned-out-of-band peers. Fluent: returns the connector.
mut thisA by-value receiver the body may also reassign. The receiver is moved into the method and consumed; the caller's value may not be used afterwards.
language reference&this
mut &this
thisThe receiver of a method. Its first parameter declares how the method takes it: &this borrows read-only, mut &this borrows exclusively, and this / mut this move the value in and consume it. In the body, this.field reaches the members.
TlsConnector::with_alpn_h2(mut this) -> TlsConnectorAdvertise HTTP/2 (and HTTP/1.1) via ALPN. Read the negotiated result back with TlsStream::negotiated_alpn. Fluent.
async function name(param: Type) -> T { ... }Compiles the function into a stackless state machine. Calling it builds a future whose output is the declared return type; nothing runs until that future is polled. Allowed on free functions, methods, and trait methods.
language referenceasync 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.
(parameter) stream: TcpStreamtype struct TcpStream {
fd: i32;
}(parameter) hostname: Strtype struct Str {
bytes: u8*;
length: u64;
}Str: a borrowed UTF-8 string slice.
std::collections::strtype struct TlsStream {
ssl: void*;
inner: TcpStream;
}TlsConnector::start_connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsHandshake, IoError>Set the socket non-blocking and mint the SSL* with the SNI and verification wiring, handing back the future that drives the handshake.
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.
type struct TlsAcceptor {
ctx: void*;
}TlsAcceptor.ctx: void*static TlsAcceptor::new(cert_path: Str, key_path: Str) -> Result<TlsAcceptor, IoError>New server context from a PEM certificate chain and private key (paths on disk). Fails InvalidInput if either file is missing or the key doesn't match the certificate.
(parameter) cert_path: Str(parameter) key_path: Strtype struct TlsAcceptor {
ctx: void*;
}async TlsAcceptor::accept(&this, stream: TcpStream) -> Result<TlsStream, IoError>Complete the server handshake over an accepted TcpStream. Consumes it; closes it on failure.
TlsAcceptor::start_accept(&this, stream: TcpStream) -> Result<TlsHandshake, IoError>Mint the SSL* and hand back the handshake future, the server-side mirror of start_connect. A socket handed over by TcpAccept is already non-blocking, but it is set here rather than assumed.
const NAME: Type = value;At module level, a true compile-time constant, conventionally SCREAMING_SNAKE_CASE. (mut at module level declares mutable global state instead.)
const ALPN_H2_HTTP11_LEN: u32 = 11;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).
namespace std::net::tls::context;TLS contexts: TlsConnector (client) and TlsAcceptor (server).
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.
async TlsAcceptor::accept(&this, stream: TcpStream) -> Result<TlsStream, IoError>Complete the server handshake over an accepted TcpStream. Consumes it; closes it on failure.
TlsConnector::start_connect(&this, stream: TcpStream, hostname: Str) -> Result<TlsHandshake, IoError>Set the socket non-blocking and mint the SSL* with the SNI and verification wiring, handing back the future that drives the handshake.
TlsAcceptor::start_accept(&this, stream: TcpStream) -> Result<TlsHandshake, IoError>Mint the SSL* and hand back the handshake future, the server-side mirror of start_connect. A socket handed over by TcpAccept is already non-blocking, but it is set here rather than assumed.
static Futures::timeout<F, O>(dur: Duration, fut: F) -> Timeout<F, O>
where F: Future<O>Run fut with a deadline dur from now.
TlsConnector::danger_accept_invalid_certs(mut this) -> TlsConnectorDisable certificate + hostname verification. Named to be ugly on purpose: only for self-signed test servers or pinned-out-of-band peers. Fluent: returns the connector.
std::net::tls::contextTlsConnector::with_alpn_h2(mut this) -> TlsConnectorAdvertise HTTP/2 (and HTTP/1.1) via ALPN. Read the negotiated result back with TlsStream::negotiated_alpn. Fluent.
TlsConnector.ctx: void*TlsConnector.verify: booleanstatic TlsConnector::new() -> Result<TlsConnector, IoError>New client context with the system trust store loaded and peer verification on by default.
std::net::tls::contextTlsStream::negotiated_alpn(&this) -> AlpnProtocolThe ALPN protocol the peer agreed on, or None if ALPN wasn't offered / negotiated. Valid only after the handshake.
TlsConnector::drop(mut &this) -> voidvia trait Drop
Release the context. Streams already minted keep their own reference and remain valid.
std::net::tls::contextIoErrorKind::InvalidInputtype struct TcpAccept {
listener: TcpListener;
rt: Reactor*;
}Accept the next incoming connection. An accepted socket does not inherit the listener's non-blocking mode, so it is set here — it is about to be used with these same futures. Owns the listener for the duration and hands it back in the TcpAccepted, so a server loop starts the next accept from that.