class Session

Handles all SSL activity for a TCP connection.

A session is created for every TCP connection where useSsl is specified. It is then passed to any registered session initialisation callbacks for customisation.

Public Functions

inline const SessionId *getSessionId() const

If available, return the current SSL Session ID.

Return values:

SessionId* – If connection hasn’t been established, may return Null

bool onAccept(TcpConnection *client, tcp_pcb *tcp)

Called when a client connection is made via server TCP socket.

  • client – The client TCP socket

  • tcp – The low-level TCP connection to use for reading and writing

Return values:

bool – true if the connection may proceed, false to abort

inline void setConnection(Connection *connection)

Called by TcpConnection to set the established SSL connection.


connection – The server connection

inline Connection *getConnection()

Get the currently active SSL connection object.

Return values:


bool onConnect(tcp_pcb *tcp)

Handle connection event.



Return values:

bool – true on success, false to abort the connection

inline bool isConnected() const

Determine if an SSL connection has been fully established.

Return values:

boolConnection state

void close()

End the session.

SSL typically sends a closing handshake at this point

int read(InputBuffer &input, uint8_t *&output)

Read data from SSL connection.

  • input – Source encrypted data

  • output – Points to decrypted content

Return values:

int – Size of decrypted data returned, or negative on error

int write(const uint8_t *data, size_t length)

Write data to SSL connection.

  • data

  • length

Return values:

int – Quantity of bytes actually written, or tcp error code

bool validateCertificate()

Called by SSL adapter when certificate validation is required.


SSL Internal method

Return values:

bool – true if validation is success, false to abort connection

void handshakeComplete(bool success)

Called by SSL adapter when handshake has been completed.


SSL Internal method


success – Indicates if handshake was successful

size_t printTo(Print &p) const

For debugging.

Public Members

String hostName

Used for SNI

KeyCertPair keyCert

Required for server, optional for client.

Options options

Various connection options.

MaxBufferSize maxBufferSize = MaxBufferSize::Default

Controls SSL RAM usage.

const CipherSuites::Array *cipherSuites = &CipherSuites::basic

Configure supported cipher suites. Default is basic.

int cacheSize = 10

Set session caching.

Server: Number of cached client sessions. Suggested value: 10.

Client: Number of cached session ids. Suggested value: 1.

ValidatorList validators

List of certificate validators used by Client.

class SessionId

Manages buffer to store SSL Session ID.

Public Functions

inline String toString() const

Return a string representation of the session ID.

struct Options

Configurable options.

Public Members

bool sessionResume

Keep a note of session ID for later re-use.

bool verifyLater

Allow handshake to complete before verifying certificate.

enum class Ssl::MaxBufferSize

Indicate to SSL how much memory (approximately) to commit for buffers.

A remote SSL server may require data transfers in large (16K) fragments, so restricting buffer sizes may cause connections to such servers to fail.

This must be balanced against other requirements for RAM by the application, therefore this setting can be used to restrict RAM usage.


The ordinal value of this enumeration corresponds to SSL fragment size as defined in Maximum Fragment Length Negotiation


enumerator Default

Let SSL implementation decide.

enumerator B512

512 bytes

enumerator K1

1024 bytes

enumerator K2
enumerator K4
enumerator K8
enumerator K16