Struct s2n_quic_tls::pool::PooledConnection
source · pub struct PooledConnection<T = Arc<dyn Pool>>where
T: Pool,{ /* private fields */ }
Expand description
A connection produced by a Pool
.
When dropped, returns ownership of the connection to
the pool that produced it by calling Pool::give
.
Implementations§
Methods from Deref<Target = Connection>§
sourcepub fn set_blinding(
&mut self,
blinding: Blinding
) -> Result<&mut Connection, Error>
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).
sourcepub fn remaining_blinding_delay(&self) -> Result<Duration, Error>
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.
sourcepub fn set_client_auth_type(
&mut self,
client_auth_type: ClientAuthType
) -> Result<&mut Connection, Error>
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.
sourcepub fn set_config(&mut self, config: Config) -> Result<&mut Connection, Error>
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>
sourcepub fn set_dynamic_record_threshold(
&mut self,
resize_threshold: u32,
timeout_threshold: u16
) -> 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.
sourcepub fn request_key_update(
&mut self,
peer_request: PeerKeyUpdate
) -> Result<&mut Connection, Error>
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.
sourcepub fn set_application_protocol_preference<P, I>(
&mut self,
protocols: P
) -> Result<&mut Connection, Error>
pub fn set_application_protocol_preference<P, I>( &mut self, protocols: P ) -> Result<&mut Connection, Error>
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>
sourcepub fn set_receive_callback(
&mut self,
callback: Option<unsafe extern "C" fn(_: *mut c_void, _: *mut u8, _: u32) -> i32>
) -> 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.
sourcepub unsafe fn set_receive_context(
&mut self,
context: *mut c_void
) -> Result<&mut Connection, Error>
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
sourcepub fn set_send_callback(
&mut self,
callback: Option<unsafe extern "C" fn(_: *mut c_void, _: *const u8, _: u32) -> i32>
) -> Result<&mut Connection, Error>
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.
sourcepub fn set_verify_host_callback<T>(
&mut self,
handler: T
) -> Result<&mut Connection, Error>where
T: 'static + VerifyHostNameCallback,
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.
sourcepub unsafe fn set_send_context(
&mut self,
context: *mut c_void
) -> Result<&mut Connection, Error>
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
sourcepub fn prefer_low_latency(&mut self) -> Result<&mut Connection, Error>
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.
sourcepub fn prefer_throughput(&mut self) -> Result<&mut Connection, Error>
pub fn prefer_throughput(&mut self) -> Result<&mut Connection, Error>
Connections prefering throughput will use large record sizes that minimize overhead.
sourcepub fn release_buffers(&mut self) -> Result<&mut Connection, Error>
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>
sourcepub fn wipe(&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
sourcepub fn poll_negotiate(&mut self) -> Poll<Result<&mut Connection, Error>>
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.
sourcepub fn poll_send(&mut self, buf: &[u8]) -> Poll<Result<usize, Error>>
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.
sourcepub fn poll_recv(&mut self, buf: &mut [u8]) -> Poll<Result<usize, Error>>
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.
sourcepub fn poll_recv_uninitialized(
&mut self,
buf: &mut [MaybeUninit<u8>]
) -> Poll<Result<usize, Error>>
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:
- It will never deinitialize any bytes in
buf
. - If it returns
Ok(n)
, then the firstn
bytes ofbuf
will have been initialized by this function.
sourcepub fn poll_flush(&mut self) -> Poll<Result<&mut Connection, Error>>
pub fn poll_flush(&mut self) -> Poll<Result<&mut Connection, Error>>
Attempts to flush any data previously buffered by a call to send.
sourcepub fn peek_len(&self) -> usize
pub fn peek_len(&self) -> usize
Gets the number of bytes that are currently available in the buffer to be read.
sourcepub fn poll_shutdown(&mut self) -> Poll<Result<&mut Connection, Error>>
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.
sourcepub fn poll_shutdown_send(&mut self) -> Poll<Result<&mut Connection, Error>>
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.
sourcepub fn set_server_name(
&mut self,
server_name: &str
) -> Result<&mut Connection, Error>
pub fn set_server_name( &mut self, server_name: &str ) -> Result<&mut Connection, Error>
Sets the server name value for the connection
sourcepub fn server_name(&self) -> Option<&str>
pub fn server_name(&self) -> Option<&str>
Get the server name associated with the connection client hello.
sourcepub fn set_session_ticket(
&mut self,
session: &[u8]
) -> Result<&mut Connection, Error>
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
sourcepub fn set_waker(
&mut self,
waker: Option<&Waker>
) -> Result<&mut Connection, Error>
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.
sourcepub fn server_name_extension_used(&mut self)
pub fn server_name_extension_used(&mut self)
Mark that the server_name extension was used to configure the connection.
sourcepub fn client_cert_used(&self) -> bool
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.
sourcepub fn client_cert_chain_bytes(&self) -> Result<Option<&[u8]>, Error>
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.
sourcepub fn client_hello(&self) -> Result<&ClientHello, Error>
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>
sourcepub fn tls_exporter(
&self,
label: &[u8],
context: &[u8],
output: &mut [u8]
) -> Result<(), 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.
sourcepub fn peer_cert_chain(&self) -> Result<CertificateChain<'static>, Error>
pub fn peer_cert_chain(&self) -> Result<CertificateChain<'static>, Error>
Returns the validated peer certificate chain.
sourcepub fn selected_cert(&self) -> Option<CertificateChain<'_>>
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>
sourcepub fn serialization_length(&self) -> Result<usize, Error>
pub fn serialization_length(&self) -> Result<usize, Error>
Retrieves the size of the serialized connection
sourcepub fn serialize(&self, output: &mut [u8]) -> Result<(), Error>
pub fn serialize(&self, output: &mut [u8]) -> Result<(), Error>
Serializes the TLS connection into the provided buffer
sourcepub fn deserialize(&mut self, input: &[u8]) -> Result<(), Error>
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>
sourcepub 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>
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>
sourcepub fn are_session_tickets_enabled(&self) -> bool
pub fn are_session_tickets_enabled(&self) -> bool
Allows the quic library to check if session tickets are expected