Session

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.

Parameters:

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.

Parameters:: connection – The server connection

inline Connection *getConnection()

Get the currently active SSL connection object.

Return values:: Connection* –

bool onConnect(tcp_pcb *tcp)

Handle connection event.

Parameters:: tcp –
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:: bool – Connection 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.

Parameters:

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.

Parameters:

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.

Note

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.

Note

SSL Internal method

Parameters:: success – Indicates if handshake was successful

size_t printTo(Print &p) const: For debugging.

Public Members

String hostName: Used for SNI https://en.wikipedia.org/wiki/Server_Name_Indication.

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.

Note

The ordinal value of this enumeration corresponds to SSL fragment size as defined in Maximum Fragment Length Negotiation https://tools.ietf.org/html/rfc6066

Values:

enumerator Default: Let SSL implementation decide.

enumerator B512: 512 bytes

enumerator K1: 1024 bytes

enumerator K2

enumerator K4

enumerator K8

enumerator K16