Struct SslConnection

pub struct SslConnection<'a, Net, C: Clock + 'a, R: RngCore + CryptoRng, CTX: DerefMut<Target = SslContext<'a, Net, C, R>>> { /* private fields */ }

An SSL connection, i.e. the main type to interact with this library

To set up the underlying Mbed TLS C library, we need raw pointers so the SslContext needs a pinned/stable memory location. Basically, we use two approaches to achieve this:

1. We use a &'a mut SslContext<...> for the lifetime of the SslConnection, i.e. the underlying SslContext can not move for that lifetime. This is implemented in e.g. SslConnection::new_dtls_client. This approach has the benefit of being heapless (it does not require alloc) which is often desirable for embedded devices.
2. We use a Box<SslConnection<...>>, i.e. the SslContext lies on the heap so it does not move in memory anymore. This is implemented in e.g. SslConnection::new_dtls_client_heap_context which is only available when the alloc feature is activated. This approach has the benefit that the SslConnection may be set up in an initializer function and can be moved around freely afterwards.

Implementations

impl<'a, 'b: 'a, U: UdpClientStack, C: Clock, R: RngCore + CryptoRng> SslConnection<'b, UdpContext<U>, C, R, &'a mut SslContext<'b, UdpContext<U>, C, R>>

pub fn new_dtls_client( ssl_context: &'a mut SslContext<'b, UdpContext<U>, C, R>, preset: Preset, ) -> Result<Self, Error>

Create a new DTLS SslConnection from an SslContext

When the alloc feature is activated, the new_dtls_client_heap_context constructor can be used with a boxed context. This enables you to freely move the connection together with the context. (otherwise the context can’t be moved after the connection is created, because its address needs to be pinned in either case)

use embedded_mbedtls::ssl::{SslConnection, SslContext, Preset};

let mut ctx = SslContext::new_udp_client_side(net_stack, clock, rng, server_addr);
let connection = SslConnection::new_dtls_client(&mut ctx, Preset::Default).unwrap();

// Now the connection is ready to use!

impl<'a, U: UdpClientStack, C: Clock, R: RngCore + CryptoRng, CTX: DerefMut<Target = SslContext<'a, UdpContext<U>, C, R>>> SslConnection<'a, UdpContext<U>, C, R, CTX>

pub fn conf_handshake_timeout(&mut self, min: Duration, max: Duration)

Set retransmit timeout values for the DTLS handshake

This method is located in the impl SslConnection block which uses the UdpContext as net context. This impl block is DTLS-specific, i.e. the method will only be available on DTLS connections because it will have no effect on a TLS connection.

The Mbed TLS documentation says the following about choosing timeout values:

Default values are from RFC 6347 section 4.2.4.1.

The ‘min’ value should typically be slightly above the expected round-trip time to your peer, plus whatever time it takes for the peer to process the message. For example, if your RTT is about 600ms and you peer needs up to 1s to do the cryptographic operations in the handshake, then you should set min slightly above 1600. Lower values of min might cause spurious resends which waste network resources, while larger value of min will increase overall latency on unreliable network links.

Messages are retransmitted up to log2(ceil(max/min)) times. For example, if min = 1s and max = 5s, the retransmit plan goes: send … 1s -> resend … 2s -> resend … 4s -> resend … 5s -> give up and return a timeout error.

If the chosen Duration is out-of-bounds regarding the underlying u32, we choose huge fallbacks to avoid panics.

impl<'a, Net, C, R, CTX> SslConnection<'a, Net, C, R, CTX>

where C: Clock, R: RngCore + CryptoRng, CTX: DerefMut<Target = SslContext<'a, Net, C, R>>,

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

Perform the ssl handshake (non-blocking)

pub fn configure_psk( &mut self, psk: &[u8], psk_identity: &[u8], ) -> Result<(), Error>

Configure pre-shared keys (PSKs) and their identities to be used in PSK-based cipher suites.

Only one PSK can be registered. If no more PSKs can be configured, SslFeatureUnavailable is returned.

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

Try to write application data bytes (non-blocking)

Returns the number of bytes actually written (may be less than data.len()).

Note:

If the requested length is greater than the maximum fragment length (either the built-in limit or the one set or negotiated with the peer), then:

• with TLS, less bytes than requested are written.
• with DTLS, a SslBadInputData Error is returned.

Attempting to write 0 bytes will result in an empty TLS application record being sent.

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

Read at most buf.len() application data bytes (non-blocking)

Returns the number of bytes actually read.

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

Notify the peer that the connection is being closed (non-blocking)

On error, the connection has to be reset to be used again.

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

Reset an already initialized SSL connection for re-use

Trait Implementations

impl<'a, Net, C, R, CTX> Drop for SslConnection<'a, Net, C, R, CTX>

where C: Clock, R: RngCore + CryptoRng, CTX: DerefMut<Target = SslContext<'a, Net, C, R>>,

fn drop(&mut self)

Executes the destructor for this type.