Struct EspTls 

pub struct EspTls<S>
where
    S: Socket,
{ /* private fields */ }

Wrapper for esp-tls module. Only supports synchronous operation for now.

Implementations

impl EspTls<InternalSocket>

pub fn new() -> Result<Self, EspError>

Create a new EspTls instance using internally-managed socket.

Errors

• ESP_ERR_NO_MEM if not enough memory to create the TLS connection

pub fn connect( &mut self, host: &str, port: u16, cfg: &Config<'_>, ) -> Result<CompletedHandshake, EspError>

Establish a TLS/SSL connection with the specified host and port, using an internally-managed socket.

Errors

• ESP_ERR_INVALID_SIZE if cfg.alpn_protos exceeds 9 elements or avg 10 bytes/ALPN
• ESP_FAIL if connection could not be established
• ESP_TLS_ERR_SSL_WANT_READ if the socket is in non-blocking mode and it is not ready for reading
• ESP_TLS_ERR_SSL_WANT_WRITE if the socket is in non-blocking mode and it is not ready for writing
• EWOULDBLOCK if the socket is in non-blocking mode and it is not ready either for reading or writing (a peculiarity/bug of the esp-tls C module)

impl<S> EspTls<S>

where S: Socket,

pub fn adopt(socket: S) -> Result<Self, EspError>

Create a new EspTls instance adopting the supplied socket. The socket should be in a connected state.

Errors

• ESP_ERR_NO_MEM if not enough memory to create the TLS connection

pub fn negotiate( &mut self, host: &str, cfg: &Config<'_>, ) -> Result<CompletedHandshake, EspError>

Establish a TLS/SSL connection using the adopted socket.

Errors

• ESP_ERR_INVALID_SIZE if cfg.alpn_protos exceeds 9 elements or avg 10 bytes/ALPN
• ESP_FAIL if connection could not be established
• ESP_TLS_ERR_SSL_WANT_READ if the socket is in non-blocking mode and it is not ready for reading
• ESP_TLS_ERR_SSL_WANT_WRITE if the socket is in non-blocking mode and it is not ready for writing
• EWOULDBLOCK if the socket is in non-blocking mode and it is not ready either for reading or writing (a peculiarity/bug of the esp-tls C module)

pub fn negotiate_server( &mut self, cfg: &ServerConfig<'_>, ) -> Result<(), EspError>

Establish a TLS/SSL connection using the adopted connection, acting as the server.

This call is blocking. On ESP-IDF >= 5.5.0 the duration is bounded by cfg.tls_handshake_timeout_ms (or the ESP-TLS default of 10 s when that field is 0). When the caller cannot afford to stall, prefer EspAsyncTls::negotiate_server, or drive a non-blocking socket manually with negotiate_server_init + negotiate_server_continue (both ESP-IDF >= 5.5.0).

Errors

• ESP_FAIL if connection could not be established

pub fn negotiate_server_init( &mut self, cfg: &ServerConfig<'_>, ) -> Result<(), EspError>

Begin a server-side TLS handshake on an already-adopted socket.

Requires ESP-IDF >= 5.5.0 with mbedTLS. The socket should typically be non-blocking. Complete the handshake by repeatedly calling Self::negotiate_server_continue until it returns Ok(()). Certificate material referenced by cfg must remain valid for the duration of this call (mbedTLS parses it here).

Errors

• ESP_FAIL / other ESP-TLS errors if session setup fails

pub fn negotiate_server_continue(&mut self) -> Result<(), EspError>

Continue a server-side handshake started with Self::negotiate_server_init.

Requires ESP-IDF >= 5.5.0 with mbedTLS.

Returns Ok(()) once the handshake is complete and the session is ready for read/write.

Errors

• ESP_TLS_ERR_SSL_WANT_READ if the socket is in non-blocking mode and it is not ready for reading
• ESP_TLS_ERR_SSL_WANT_WRITE if the socket is in non-blocking mode and it is not ready for writing
• ESP_FAIL if the handshake failed; drop the connection

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

Read in the supplied buffer. Returns the number of bytes read.

Errors

• ESP_TLS_ERR_SSL_WANT_READ if the socket is in non-blocking mode and it is not ready for reading
• ESP_TLS_ERR_SSL_WANT_WRITE if the socket is in non-blocking mode and it is not ready for writing
• Any other EspError for a general error

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

Write the supplied buffer. Returns the number of bytes written.

Errors

• ESP_TLS_ERR_SSL_WANT_READ if the socket is in non-blocking mode and it is not ready for reading
• ESP_TLS_ERR_SSL_WANT_WRITE if the socket is in non-blocking mode and it is not ready for writing
• Any other EspError for a general error

pub fn write_all(&mut self, buf: &[u8]) -> Result<(), EspError>

pub fn context_handle(&self) -> *mut esp_tls

Trait Implementations

impl<S> Drop for EspTls<S>

where S: Socket,

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<S> ErrorType for EspTls<S>

where S: Socket,

type Error = EspIOError

Error type of all the IO operations on this type.

impl<S> Read for EspTls<S>

where S: Socket,

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

Read some bytes from this source into the specified buffer, returning how many bytes were read.

fn read_exact( &mut self, buf: &mut [u8], ) -> Result<(), ReadExactError<Self::Error>>

Read the exact number of bytes required to fill buf.

impl<S> Write for EspTls<S>

where S: Socket,

fn write(&mut self, buf: &[u8]) -> Result<usize, EspIOError>

Write a buffer into this writer, returning how many bytes were written.

fn flush(&mut self) -> Result<(), EspIOError>

Flush this output stream, blocking until all intermediately buffered contents reach their destination.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Self::Error>

Write an entire buffer into this writer.

fn write_fmt( &mut self, fmt: Arguments<'_>, ) -> Result<(), WriteFmtError<Self::Error>>

Write a formatted string into this writer, returning any error encountered.