BearSSLSocket

class WiFiBearSSLSocket

A wrapper over a socket that adds SSL using Bear SSL

This class is only available if Bear SSL is present during the compilation. It is detected via presence of either <bearssl/bearssl.h> or <bearssl.h> header. You can most easily obtain Bear SSL via ArduinoBearSSL library.

This class takes a pre-existing socket obtained from elsewhere and assumes ownership over it. Like the original socket it is movable and move assignable but not copyable or copy assignable.

Both blocking and non-blocking sockets are supported.

Public Types

enum Error

Error codes specific to this class. These may be returned from WiFiBearSSLSocket::lastError().

Their range is such that it will not overlap with plain socket errors.

Values:

enumerator NotInitialized

br_ssl_engine_context is not fully initialized yet

enumerator ProtocolError

SSL protocol error, call br_ssl_engine_last_error() on the engine to find out more.

enumerator MustRecv

Cannot send() now. You must recv() first.

enumerator MustSend

Cannot recv() now. You must send() first.

Public Functions

WiFiBearSSLSocket() = default

Creates an invalid socket.

inline WiFiBearSSLSocket(WiFiSocket &&socket, br_ssl_engine_context *eng)

Creates a socket

This method never fails. The source socket should be in connected state and ready to use - you will not be able to access it after this call.

Parameters:

• socket – the plain socket to assume ownership of

• eng – Bear SSL engine context.

inline WiFiBearSSLSocket(WiFiBearSSLSocket &&src)

Moving a socket

The source socket is left in an invalid state

inline WiFiBearSSLSocket &operator=(WiFiBearSSLSocket &&src)

Move-assigning a socket

The source socket is left in an invalid state

inline explicit operator bool() const

Tests whether the socket is invalid.

A socket is in an invalid state when it represents “no socket”. A valid socket never becomes invalid unless it is moved out or closed. Similarly an invalid socket never becomes valid unless moved-in from a valid socket.

inline void close()

Manually close the socket

This makes this object an invalid socket. Note that this method does NOT gracefully close SSL connection. It just brute-force closes the socket. Call finish() to gracefully close.

bool handshake()

Perform an SSL handshake.

Due to Bear SSL design, this method is not strictly necessary. If you don’t call it and just start using send() or recv() the handshake will be performed automatically for you. However, it is sometime convenient to isolate handshake stage in its own step so this method is provided for convenience and compatibility with other libraries.

Returns:

success flag. Check lastError() for more information about failure

int32_t send(const void *buf, uint16_t size)

Sends data to remote endpoint

Returns:

the amount of data actually sent or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

int32_t recv(void *buf, uint16_t size)

Receives data from remote endpoint

Returns:

the amount of data actually read or -1 on failure. Check lastError() for more information about failure. The type of the return value is int32_t to accommodate -1. When non-negative it will never be bigger than the size parameter.

bool flush()

Sends any buffered data to the remote endpoint

Bear SSL buffers the data you send() and doesn’t necessarily immediately send it over the network. This method allows you to send any buffered data immediately.

Returns:

success flag. Check lastError() for more information about failure

bool finish()

Gracefully closes SSL connection

When this method returns true the underlying socket is also closed. For non-blocking sockets it might return EWOULDBLOCK so be prepared to call it multiple times.

Returns:

success flag. Check lastError() for more information about failure

Public Static Functions

static inline int lastError()

Retrieves error (if any) of the last method call.

Last error is always set, whether the call failed or succeeded.

Returns:

either a WiFiSocket::lastError() code (if the underlying socket operation failed) or one of the SSLError error codes. The ranges of these errors are disjoint.