Struct s2n_quic::provider::tls::default::pool::PooledConnection

pub struct PooledConnection<T = Arc<dyn Pool>>
where
    T: Pool,
{ /* private fields */ }

A connection produced by a Pool.

When dropped, returns ownership of the connection to the pool that produced it by calling Pool::give.

Implementations

impl<T> PooledConnection<T>

where T: Pool + Clone,

pub fn new(pool: &T) -> Result<PooledConnection<T>, Error>

Methods from Deref<Target = Connection>

pub fn set_blinding( &mut self, blinding: Blinding ) -> Result<&mut Connection, Error>

can be used to configure s2n to either use built-in blinding (set blinding to Blinding::BuiltIn) or self-service blinding (set blinding to Blinding::SelfService).

pub fn remaining_blinding_delay(&self) -> Result<Duration, Error>

Reports the remaining nanoseconds before the connection may be gracefully shutdown.

This method is expected to succeed, but could fail if the underlying C call encounters errors. Failure indicates that calls to Self::poll_shutdown will also fail and that a graceful two-way shutdown of the connection will not be possible.

pub fn set_client_auth_type( &mut self, client_auth_type: ClientAuthType ) -> Result<&mut Connection, Error>

Sets whether or not a Client Certificate should be required to complete the TLS Connection.

If this is set to ClientAuthType::Optional the server will request a client certificate but allow the client to not provide one. Rejecting a client certificate when using ClientAuthType::Optional will terminate the handshake.

pub fn set_config(&mut self, config: Config) -> Result<&mut Connection, Error>

Associates a configuration object with a connection.

pub fn set_security_policy( &mut self, policy: &Policy ) -> Result<&mut Connection, Error>

pub fn set_dynamic_record_threshold( &mut self, resize_threshold: u32, timeout_threshold: u16 ) -> Result<&mut Connection, Error>

provides a smooth transition from s2n_connection_prefer_low_latency to s2n_connection_prefer_throughput.

s2n_send uses small TLS records that fit into a single TCP segment for the resize_threshold bytes (cap to 8M) of data and reset record size back to a single segment after timeout_threshold seconds of inactivity.

pub fn request_key_update( &mut self, peer_request: PeerKeyUpdate ) -> Result<&mut Connection, Error>

Signals the connection to do a key_update at the next possible opportunity. Note that the resulting key update message will not be sent until send is called on the connection.

peer_request indicates if a key update should also be requested of the peer. When set to KeyUpdateNotRequested, then only the sending key of the connection will be updated. If set to KeyUpdateRequested, then the sending key of conn will be updated AND the peer will be requested to update their sending key. Note that s2n-tls currently only supports peer_request being set to KeyUpdateNotRequested and will return an error if any other value is used.

pub fn set_application_protocol_preference<P, I>( &mut self, protocols: P ) -> Result<&mut Connection, Error>

where P: IntoIterator<Item = I>, I: AsRef<[u8]>,

sets the application protocol preferences on an s2n_connection object.

protocols is a list in order of preference, with most preferred protocol first, and of length protocol_count. When acting as a client the protocol list is included in the Client Hello message as the ALPN extension. As a server, the list is used to negotiate a mutual application protocol with the client. After the negotiation for the connection has completed, the agreed upon protocol can be retrieved with s2n_get_application_protocol

pub fn append_application_protocol_preference( &mut self, protocol: &[u8] ) -> Result<&mut Connection, Error>

pub fn set_receive_callback( &mut self, callback: Option<unsafe extern "C" fn(_: *mut c_void, _: *mut u8, _: u32) -> i32> ) -> Result<&mut Connection, Error>

may be used to receive data with callbacks defined by the user.

pub unsafe fn set_receive_context( &mut self, context: *mut c_void ) -> Result<&mut Connection, Error>

Safety

The context pointer must live at least as long as the connection

pub fn set_send_callback( &mut self, callback: Option<unsafe extern "C" fn(_: *mut c_void, _: *const u8, _: u32) -> i32> ) -> Result<&mut Connection, Error>

may be used to receive data with callbacks defined by the user.

pub fn set_verify_host_callback<T>( &mut self, handler: T ) -> Result<&mut Connection, Error>

where T: 'static + VerifyHostNameCallback,

Sets the callback to use for verifying that a hostname from an X.509 certificate is trusted.

The callback may be called more than once during certificate validation as each SAN on the certificate will be checked.

Corresponds to the underlying C API s2n_connection_set_verify_host_callback.

pub unsafe fn set_send_context( &mut self, context: *mut c_void ) -> Result<&mut Connection, Error>

Safety

The context pointer must live at least as long as the connection

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

Connections prefering low latency will be encrypted using small record sizes that can be decrypted sooner by the recipient.

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

Connections prefering throughput will use large record sizes that minimize overhead.

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

wipes and free the in and out buffers associated with a connection.

This function may be called when a connection is in keep-alive or idle state to reduce memory overhead of long lived connections.

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

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

wipes an existing connection and allows it to be reused.

This method erases all data associated with a connection including pending reads. This function should be called after all I/O is completed and s2n_shutdown has been called. Reusing the same connection handle(s) is more performant than repeatedly calling s2n_connection_new and s2n_connection_free

pub fn poll_negotiate(&mut self) -> Poll<Result<&mut Connection, Error>>

Performs the TLS handshake to completion

Multiple callbacks can be configured for a connection and config, but Self::poll_negotiate() can only execute and block on one callback at a time. The handshake is sequential, not concurrent, and stops execution when it encounters an async callback.

The handshake does not continue execution (and therefore can’t call any other callbacks) until the blocking async task reports completion.

pub fn poll_send(&mut self, buf: &[u8]) -> Poll<Result<usize, Error>>

Encrypts and sends data on a connection where negotiate has succeeded.

Returns the number of bytes written, and may indicate a partial write.

pub fn poll_recv(&mut self, buf: &mut [u8]) -> Poll<Result<usize, Error>>

Reads and decrypts data from a connection where negotiate has succeeded.

Returns the number of bytes read, and may indicate a partial read. 0 bytes returned indicates EOF due to connection closure.

pub fn poll_recv_uninitialized( &mut self, buf: &mut [MaybeUninit<u8>] ) -> Poll<Result<usize, Error>>

Reads and decrypts data from a connection where negotiate has succeeded to a uninitialized buffer.

Returns the number of bytes read, and may indicate a partial read. 0 bytes returned indicates EOF due to connection closure.

Safety: this function is always safe to call, and additionally:

1. It will never deinitialize any bytes in buf.
2. If it returns Ok(n), then the first n bytes of buf will have been initialized by this function.

pub fn poll_flush(&mut self) -> Poll<Result<&mut Connection, Error>>

Attempts to flush any data previously buffered by a call to send.

pub fn peek_len(&self) -> usize

Gets the number of bytes that are currently available in the buffer to be read.

pub fn poll_shutdown(&mut self) -> Poll<Result<&mut Connection, Error>>

Attempts a graceful shutdown of the TLS connection.

The shutdown is not complete until the necessary shutdown messages have been successfully sent and received. If the peer does not respond correctly, the graceful shutdown may fail.

pub fn poll_shutdown_send(&mut self) -> Poll<Result<&mut Connection, Error>>

Attempts a graceful shutdown of the write side of a TLS connection.

Unlike Self::poll_shutdown, no reponse from the peer is necessary. If using TLS1.3, the connection can continue to be used for reading afterwards.

pub fn alert(&self) -> Option<u8>

Returns the TLS alert code, if any

pub fn set_server_name( &mut self, server_name: &str ) -> Result<&mut Connection, Error>

Sets the server name value for the connection

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

Get the server name associated with the connection client hello.

pub fn set_session_ticket( &mut self, session: &[u8] ) -> Result<&mut Connection, Error>

Adds a session ticket from a previous TLS connection to create a resumed session

pub fn set_waker( &mut self, waker: Option<&Waker> ) -> Result<&mut Connection, Error>

Sets a Waker on the connection context or clears it if None is passed.

pub fn waker(&self) -> Option<&Waker>

Returns the Waker set on the connection context.

pub fn server_name_extension_used(&mut self)

Mark that the server_name extension was used to configure the connection.

pub fn client_cert_used(&self) -> bool

Check if client auth was used for a connection.

This is only relevant if `ClientAuthType::Optional was used.

pub fn client_cert_chain_bytes(&self) -> Result<Option<&[u8]>, Error>

Retrieves the raw bytes of the client cert chain received from the peer, if present.

pub fn client_hello(&self) -> Result<&ClientHello, Error>

Returns a reference to the ClientHello associated with the connection.

use s2n_tls::client_hello::{ClientHello, FingerprintType};
use s2n_tls::connection::Connection;
use s2n_tls::enums::Mode;

let mut conn = Connection::new(Mode::Server);
let mut client_hello: &ClientHello = conn.client_hello().unwrap();
let mut hash = Vec::new();
drop(conn);
client_hello.fingerprint_hash(FingerprintType::JA3, &mut hash);

The compilation could be failing for a variety of reasons, so make sure that the test case is actually good.

use s2n_tls::client_hello::{ClientHello, FingerprintType};
use s2n_tls::connection::Connection;
use s2n_tls::enums::Mode;

let mut conn = Connection::new(Mode::Server);
let mut client_hello: &ClientHello = conn.client_hello().unwrap();
let mut hash = Vec::new();
client_hello.fingerprint_hash(FingerprintType::JA3, &mut hash);
drop(conn);

pub fn actual_protocol_version(&self) -> Result<Version, Error>

pub fn handshake_type(&self) -> Result<&str, Error>

pub fn cipher_suite(&self) -> Result<&str, Error>

pub fn selected_curve(&self) -> Result<&str, Error>

pub fn selected_signature_algorithm(&self) -> Result<SignatureAlgorithm, Error>

pub fn selected_hash_algorithm(&self) -> Result<HashAlgorithm, Error>

pub fn selected_client_signature_algorithm( &self ) -> Result<Option<SignatureAlgorithm>, Error>

pub fn selected_client_hash_algorithm( &self ) -> Result<Option<HashAlgorithm>, Error>

pub fn tls_exporter( &self, label: &[u8], context: &[u8], output: &mut [u8] ) -> Result<(), Error>

Provides access to the TLS-Exporter functionality.

See https://datatracker.ietf.org/doc/html/rfc5705 and https://www.rfc-editor.org/rfc/rfc8446.

This is currently only available with TLS 1.3 connections which have finished a handshake.

pub fn peer_cert_chain(&self) -> Result<CertificateChain<'static>, Error>

Returns the validated peer certificate chain.

pub fn selected_cert(&self) -> Option<CertificateChain<'_>>

Get the certificate used during the TLS handshake

• If self is a server connection, the certificate selected will depend on the ServerName sent by the client and supported ciphers.
• If self is a client connection, the certificate sent in response to a CertificateRequest message is returned. Currently s2n-tls supports loading only one certificate in client mode. Note that not all TLS endpoints will request a certificate.

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

pub fn serialization_length(&self) -> Result<usize, Error>

Retrieves the size of the serialized connection

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

Serializes the TLS connection into the provided buffer

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

Deserializes the input buffer into a new TLS connection that can send/recv data from the original peer.

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

pub fn set_quic_transport_parameters( &mut self, buffer: &[u8] ) -> Result<&mut Connection, Error>

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

pub unsafe fn set_secret_callback( &mut self, callback: Option<unsafe extern "C" fn(_: *mut c_void, _: *mut s2n_connection, _: u32, _: *mut u8, _: u8) -> i32>, context: *mut c_void ) -> Result<&mut Connection, Error>

Safety

The context pointer must live at least as long as the connection

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

pub fn are_session_tickets_enabled(&self) -> bool

Allows the quic library to check if session tickets are expected

Trait Implementations

impl<T> AsMut<Connection> for PooledConnection<T>

where T: Pool,

fn as_mut(&mut self) -> &mut Connection

Converts this type into a mutable reference of the (usually inferred) input type.

impl<T> AsRef<Connection> for PooledConnection<T>

where T: Pool,

fn as_ref(&self) -> &Connection

Converts this type into a shared reference of the (usually inferred) input type.

impl<T> Debug for PooledConnection<T>

where T: Debug + Pool,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<T> Deref for PooledConnection<T>

where T: Pool,

type Target = Connection

The resulting type after dereferencing.

fn deref(&self) -> &<PooledConnection<T> as Deref>::Target

Dereferences the value.

impl<T> DerefMut for PooledConnection<T>

where T: Pool,

fn deref_mut(&mut self) -> &mut <PooledConnection<T> as Deref>::Target

Mutably dereferences the value.

impl<T> Drop for PooledConnection<T>

where T: Pool,

fn drop(&mut self)

Executes the destructor for this type.