Struct Session

Source

pub struct Session<'a, T>where
    T: Read + Write,
{ /* private fields */ }

Expand description

An async TLS session over a stream represented by embedded-io-async’s Read and Write traits.

Implementations§

Source §

impl<'a, T> Session<'a, T>
where T: Read + Write,

Source

pub fn new( tls: TlsReference<'a>, stream: T, config: &SessionConfig<'a>, ) -> Result<Self, SessionError>

Create a session for a TLS stream.

§Arguments

tls - A reference to the active Tls instance.
stream - The stream for the connection, implementing Read and Write.
`config`` - The session configuration

§Returns

A Session instance or a TlsError on failure.

Source

pub fn tls_verification_details(&self) -> u32

Get the TLS verification details

The details are a bitmask of various flags indicating the result of the certificate verification.

§Returns

0 if verification succeeded
A bitmask of verification failure flags otherwise

NOTE: This function should be called only after a connect() call.

Source

pub fn tls_alpn(&self) -> Option<&CStr>

Get the negotiated ALPN protocol, if any.

NOTE: This function should be called only after a connect() call.

Source

pub fn stream(&mut self) -> &mut T

Get a mutable reference to the underlying stream

Source

pub fn set_server_name( &mut self, server_name: &CStr, ) -> Result<(), SessionError>

Set the server name for the TLS connection.

Must be called before the handshake is triggered (by connect, connect_with_session, read, write, or split); changing the server name on an already-connected session is rejected, because the saved session would otherwise be bound to a name that was not used to negotiate it.

§Arguments

server_name: The server name as a C string

Source

pub async fn connect(&mut self) -> Result<(), SessionError>

Negotiate the TLS connection

This function will perform the TLS handshake with the server.

Note that calling it is not mandatory, because the TLS session is anyway negotiated during the first read or write operation, or when splitting the session.

§Cancel safety

NOT cancel-safe. The handshake resets the SSL context (mbedtls_ssl_session_reset) before driving it across multiple .await points; if this future is dropped mid-handshake, the local TLS state is left partway through a handshake the peer may have advanced, and a retry can reset it out from under the peer.

Source

pub async fn connect_with_session( &mut self, saved_session: &SavedSession, ) -> Result<(), SessionError>

Negotiate the TLS connection attempting to reuse a previously captured session.

Use Session::save to get a copy of the session to use here

§Cancel safety

NOT cancel-safe. Same as Session::connect.

Source

pub async fn split( &mut self, ) -> Result<(SessionRead<'_, impl Read + '_>, SessionWrite<'_, impl Write + '_>), SessionError>
where T: Split,

Split the TLS session into read and write halves

§Returns

A tuple containing the read and write halves of the session

§Cancel safety

NOT cancel-safe. This negotiates the connection first (see Session::connect); once connected the split itself has no further .await points.

Source

pub async fn read(&mut self, buf: &mut [u8]) -> Result<usize, SessionError>

Read unencrypted data from the TLS connection

§Arguments

buf - The buffer to read the data into

§Returns

The number of bytes read or an error

§Cancel safety

NOT cancel-safe. This drives MbedTLS across multiple .await points. A dropped read does not lose application data (a buffered transport byte is kept, and bytes already consumed by MbedTLS live in the SSL context), but it can leave partial TLS input/record state, so re-issuing is not side-effect-free.

Source

pub async fn write(&mut self, data: &[u8]) -> Result<usize, SessionError>

Write unencrypted data to the TLS connection

§Arguments:

data - The data to write

§Returns:

The number of bytes written or an error

§Cancel safety

NOT cancel-safe, but never misreports. If this future is dropped after MbedTLS has buffered part of data into a record (an internal WANT_WRITE), that record may be partially on the wire, so the write is not side-effect-free. However the accounting stays correct: the next write/flush/close first finishes sending that pending record (it is never attributed to the next call’s buffer), so re-issuing with a different buffer is safe and returns only that buffer’s own byte count.

Source

pub async fn flush(&mut self) -> Result<(), SessionError>

Flush the TLS connection

This function will flush the TLS connection, ensuring that all data is sent.

§Returns:

An error if the flush failed

§Cancel safety

NOT cancel-safe. A dropped flush may leave a queued transport byte unsent or the underlying stream only partially flushed, so it is not side-effect-free; re-flushing is generally fine if the underlying Write is well-behaved.

Source