Struct s2n_quic_tls::connection::Connection
source · pub struct Connection { /* private fields */ }
Implementations§
source§impl Connection
impl Connection
sourcepub fn new(mode: Mode) -> Connection
pub fn new(mode: Mode) -> Connection
§Warning
The newly created connection uses the default security policy.
Consider changing this depending on your security and compatibility requirements
by calling Connection::set_security_policy
.
Alternatively, you can use crate::config::Builder
, crate::config::Builder::set_security_policy
,
and Connection::set_config
to set the policy on the Config instead of on the Connection.
See the s2n-tls usage guide:
https://aws.github.io/s2n-tls/usage-guide/ch06-security-policies.html
pub fn new_client() -> Connection
pub fn new_server() -> 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 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 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 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 session_ticket_length(&self) -> Result<usize, Error>
pub fn session_ticket_length(&self) -> Result<usize, Error>
Retrieves the size of the session ticket.
sourcepub fn session_ticket(&self, output: &mut [u8]) -> Result<usize, Error>
pub fn session_ticket(&self, output: &mut [u8]) -> Result<usize, Error>
Serializes the session state from the connection into output
and returns
the length of the session ticket.
If the buffer does not have the size for the session_ticket,
Error::INVALID_INPUT
is returned.
Note: This function is not recommended for > TLS1.2 because in TLS1.3 servers can send multiple session tickets and this will return only the most recently received ticket.
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;
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();
drop(conn);
client_hello.raw_message();
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;
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();
client_hello.raw_message();
drop(conn);
sourcepub fn actual_protocol_version(&self) -> Result<Version, Error>
pub fn actual_protocol_version(&self) -> Result<Version, Error>
Access the protocol version selected for the connection.
sourcepub fn client_hello_is_sslv2(&self) -> Result<bool, Error>
pub fn client_hello_is_sslv2(&self) -> Result<bool, Error>
Detects if the client hello is using the SSLv2 format.
s2n-tls will not negotiate SSLv2, but will accept SSLv2 ClientHellos advertising a higher protocol version like SSLv3 or TLS1.0. Connection::actual_protocol_version() can be used to retrieve the protocol version that is actually used on the connection.
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 application_protocol(&self) -> Option<&[u8]>
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.
sourcepub fn resumed(&self) -> bool
pub fn resumed(&self) -> bool
Determines whether the connection was resumed from an earlier handshake.
sourcepub fn set_application_context<T>(&mut self, app_context: T)
pub fn set_application_context<T>(&mut self, app_context: T)
Associates an arbitrary application context with the Connection to be later retrieved via
the Self::application_context()
and Self::application_context_mut()
APIs.
This API will override an existing application context set on the Connection.
sourcepub fn application_context<T>(&self) -> Option<&T>
pub fn application_context<T>(&self) -> Option<&T>
Retrieves a reference to the application context associated with the Connection.
If an application context hasn’t already been set on the Connection, or if the set application context isn’t of type T, None will be returned.
To set a context on the connection, use Self::set_application_context()
. To retrieve a
mutable reference to the context, use Self::application_context_mut()
.
sourcepub fn application_context_mut<T>(&mut self) -> Option<&mut T>
pub fn application_context_mut<T>(&mut self) -> Option<&mut T>
Retrieves a mutable reference to the application context associated with the Connection.
If an application context hasn’t already been set on the Connection, or if the set application context isn’t of type T, None will be returned.
To set a context on the connection, use Self::set_application_context()
. To retrieve an
immutable reference to the context, use Self::application_context()
.
source§impl Connection
impl Connection
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
Trait Implementations§
source§impl AsMut<Connection> for Connection
impl AsMut<Connection> for Connection
source§fn as_mut(&mut self) -> &mut Connection
fn as_mut(&mut self) -> &mut Connection
source§impl<T> AsMut<Connection> for PooledConnection<T>where
T: Pool,
impl<T> AsMut<Connection> for PooledConnection<T>where
T: Pool,
source§fn as_mut(&mut self) -> &mut Connection
fn as_mut(&mut self) -> &mut Connection
source§impl AsRef<Connection> for Connection
impl AsRef<Connection> for Connection
source§fn as_ref(&self) -> &Connection
fn as_ref(&self) -> &Connection
source§impl<T> AsRef<Connection> for PooledConnection<T>where
T: Pool,
impl<T> AsRef<Connection> for PooledConnection<T>where
T: Pool,
source§fn as_ref(&self) -> &Connection
fn as_ref(&self) -> &Connection
source§impl Debug for Connection
impl Debug for Connection
source§impl Drop for Connection
impl Drop for Connection
impl Send for Connection
§Safety
s2n_connection objects can be sent across threads
impl Sync for Connection
§Sync
Although NonNull isn’t Sync and allows access to mutable pointers even from immutable references, the Connection interface enforces that all mutating methods correctly require &mut self.
Developers and reviewers MUST ensure that new methods correctly use either &self or &mut self depending on their behavior. No mechanism enforces this.
Note: Although non-mutating methods like getters should be thread-safe by definition, technically the only thread safety guarantee provided by the underlying C library is that s2n_send and s2n_recv can be called concurrently.