rama::tls::boring::core

Module ssl

Available on crate feature boring only.

Expand description

SSL/TLS support.

SslConnector and SslAcceptor should be used in most cases - they handle configuration of the OpenSSL primitives for you.

§Examples

To connect as a client to a remote server:

use rama_boring::ssl::{SslMethod, SslConnector};
use std::io::{Read, Write};
use std::net::TcpStream;

let connector = SslConnector::builder(SslMethod::tls()).unwrap().build();

let stream = TcpStream::connect("google.com:443").unwrap();
let mut stream = connector.connect(Some("google.com"), stream).unwrap();

stream.write_all(b"GET / HTTP/1.0\r\n\r\n").unwrap();
let mut res = vec![];
stream.read_to_end(&mut res).unwrap();
println!("{}", String::from_utf8_lossy(&res));

To accept connections as a server from remote clients:

use rama_boring::ssl::{SslMethod, SslAcceptor, SslStream, SslFiletype};
use std::net::{TcpListener, TcpStream};
use std::sync::Arc;
use std::thread;


let mut acceptor = SslAcceptor::mozilla_intermediate(SslMethod::tls()).unwrap();
acceptor.set_private_key_file("key.pem", SslFiletype::PEM).unwrap();
acceptor.set_certificate_chain_file("certs.pem").unwrap();
acceptor.check_private_key().unwrap();
let acceptor = Arc::new(acceptor.build());

let listener = TcpListener::bind("0.0.0.0:8443").unwrap();

fn handle_client(stream: SslStream<TcpStream>) {
    // ...
}

for stream in listener.incoming() {
    match stream {
        Ok(stream) => {
            let acceptor = acceptor.clone();
            thread::spawn(move || {
                let stream = acceptor.accept(stream).unwrap();
                handle_client(stream);
            });
        }
        Err(e) => { /* connection failed */ }
    }
}

§Panics in callbacks and streams

A panic never unwinds through BoringSSL. A panicking callback, future, finish closure or signer fails its operation with an error that carries the panic message (“callback panicked: …”); pending asynchronous work is dropped and never resumed; a panic while dropping it, or a waker, is contained too. A panicking transport stream fails the operation with an I/O error and is never used again. Callbacks that only observe (info, keylog, message, new and removed sessions) and session lookups cannot fail the handshake: their panics are contained, and a lookup reports a cache miss. A verify callback that panics records a failed verification, which, as for any verification result, only fails the handshake when the verify mode requires it. The panic hook still runs for every panic.

This relies on unwinding: with panic = "abort", or a panic hook that aborts, every panic aborts as usual. A destructor that panics while its own panic unwinds aborts too, as in any Rust code.

Modules§

quic: Transport-independent TLS handshakes for QUIC.

Structs§

AlpnError: An error returned from an ALPN selection callback.
AsyncPrivateKeyMethodError: A fatal error to be returned from async private key methods.
AsyncSelectCertError: A fatal error to be returned from async select certificate callbacks.
CertificateCompressionAlgorithm
CertificateSelection: Certificate-selection state, available only while the selection callback runs. Copy request metadata before moving it into an asynchronous operation. Borrowed metadata prevents mutating the SSL while that metadata is still used:
CipherBits: Information about the state of a cipher.
ClientHello
ClientHelloShape: The cross-cutting choices that shape one connection’s ClientHello.
CompliancePolicy: A compliance policy.
ConnectConfiguration: A type which allows for configuration of a client-side TLS session before connection.
EchGreaseShape: The algorithms and lengths of an ECH GREASE extension, never its keys or bytes.
Error: A general SSL error, based on SSL_ERROR_* error codes.
ErrorCode: SSL_ERROR_* error code returned from SSL functions.
ExtensionType: Extension types, to be used with ClientHello::get_extension.
GetSessionPendingError: Error returned by the callback to get a session when operation could not complete and should be retried later.
GreaseLists: ClientHello lists that get a native GREASE value, first in the list (for extensions: first and last). This only applies to native lists: a list or extension order set explicitly is exact, and its GREASE codepoints are its only GREASE slots.
MidHandshakeSslStream: An SSL stream midway through the handshake process.
NameType: An identifier of a session name type.
PrivateKeyMethodError: An error returned from a private key method.
SelectCertError: An error returned from a certificate selection callback.
ShutdownState: The shutdown state of a session.
SniError: An error returned from the SNI callback.
Ssl: The state of an SSL/TLS session.
Ssl3AlertLevel
SslAcceptor: A type which wraps server-side streams in a TLS session.
SslAcceptorBuilder: A builder for SslAcceptors.
SslAlert: An SSL/TLS alert.
SslCipher: Information about a cipher.
SslCipherRef: Reference to an SslCipher.
SslConnector: A type which wraps client-side streams in a TLS session.
SslConnectorBuilder: A builder for SslConnectors.
SslContentType: The record content type of an observed message.
SslContext: A context object for TLS streams.
SslContextBuilder: A builder for SslContexts.
SslContextRef: A borrowed reference to a SslContext.
SslCredential: A credential.
SslCredentialBuilder: A builder for SslCredential.
SslCredentialRef: A borrowed reference to a SslCredential.
SslCurve: A TLS Curve.
SslEarlyDataReason: Why 0-RTT data was or was not accepted on a connection.
SslEchKeys
SslEchKeysRef: A borrowed reference to a SslEchKeys.
SslFiletype: An identifier of the format of a certificate or key file.
SslInfoCallbackAlert
SslInfoCallbackMode: Options controlling the behavior of the info callback.
SslMessage: A protocol message observed by a message callback.
SslMethod: A type specifying the kind of protocol an SslContext will speak.
SslMode: Options controlling the behavior of an SslContext.
SslOptions: Options controlling the behavior of an SslContext.
SslRef: A borrowed reference to a Ssl.
SslRenegotiateMode: How a client handles a TLS 1.2 server’s renegotiation request.
SslSession: An encoded SSL session.
SslSessionCacheMode: Options controlling the behavior of session caching.
SslSessionRef: A borrowed reference to a SslSession.
SslSignatureAlgorithm: A signature verification algorithm.
SslStream: A TLS session over a stream.
SslStreamBuilder: A partially constructed SslStream, useful for unusual handshakes.
SslVerifyMode: Options controlling the behavior of certificate verification.
SslVersion: An SSL/TLS protocol version.
StatusType: An identifier of a certificate status type.

Enums§

EchGreaseCipherSuite: HPKE cipher suites supported for ECH GREASE. The KEM is always DHKEM(X25519, HKDF-SHA256), with a 32-byte encapsulated key.
GreaseValues: How GREASE values are chosen.
HandshakeError: An error or intermediate state after a TLS handshake attempt.
Padding: ClientHello padding.
ShutdownResult: The result of a shutdown request.
SslInfoCallbackValue: The value argument to an info callback. The most-significant byte is the alert level, while the least significant byte is the alert itself.
SslVerifyError
TicketKeyCallbackResult: Ticket key callback status.
UnknownValues: What to do with listed values a connection cannot negotiate: unknown extensions, groups, versions and signature algorithms.

Traits§

AsyncPrivateKeyMethod: Describes async private key hooks. This is used to off-load signing operations to a custom, potentially asynchronous, backend. Metadata about the key such as the type and size are parsed out of the certificate.
CertificateCompressor: Describes certificate compression algorithm. Implementation MUST implement transformation at least in one direction.
PrivateKeyMethod: Describes private key hooks. This is used to off-load signing operations to a custom, potentially asynchronous, backend. Metadata about the key such as the type and size are parsed out of the certificate.

Functions§

select_next_proto: A standard implementation of protocol selection for Application Layer Protocol Negotiation (ALPN).

Type Aliases§

BoxCertificateFinish: Installs the credentials once a BoxCertificateFuture completes. Runs synchronously on the polling thread, at most once; never after cancellation.
BoxCertificateFuture: Future returned by SslContextBuilder::set_async_certificate_callback. It owns its inputs; it cannot retain a borrow of the TLS connection or request:
BoxCustomVerifyFinish: The type of callbacks returned by BoxCustomVerifyFuture methods.
BoxCustomVerifyFuture: The type of futures to pass to SslContextBuilder::set_async_custom_verify_callback.
BoxGetSessionFinish: The type of callbacks returned by BoxSelectCertFuture methods.
BoxGetSessionFuture: The type of futures to pass to SslContextBuilder::set_async_get_session_callback.
BoxPrivateKeyMethodFinish: The type of callbacks returned by BoxPrivateKeyMethodFuture.
BoxPrivateKeyMethodFuture: The type of futures returned by AsyncPrivateKeyMethod methods.
BoxSelectCertFinish: The type of callbacks returned by BoxSelectCertFuture methods.
BoxSelectCertFuture: The type of futures to pass to SslContextBuilder::set_async_select_certificate_callback.
ExDataFuture: Convenience alias for futures stored in Ssl ex data by SslContextBuilder methods.

Module ssl

Module ssl Copy item path

§Examples

§Panics in callbacks and streams

Modules§

Structs§

Enums§

Traits§

Functions§

Type Aliases§

Module ssl