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 Types

using InitDelegate = Delegate<void(Session &session)>

Public Functions

~Session()
const SessionId *getSessionId() const

If available, return the current SSL Session ID.

Return Value
  • 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 Value
  • bool: true if the connection may proceed, false to abort

void setConnection(Connection *connection)

Called by TcpConnection to set the established SSL connection.

Parameters
  • connection: The server connection

Connection *getConnection()

Get the currently active SSL connection object.

Return Value
  • Connection*:

bool onConnect(tcp_pcb *tcp)

Handle connection event.

Parameters
  • tcp:
Return Value
  • bool: true on success, false to abort the connection

bool isConnected() const

Determine if an SSL connection has been fully established.

Return Value

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 Value
  • 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 Value
  • 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 Value
  • 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

const uint8_t *getValue() const
unsigned getLength() const
bool isValid() const
bool assign(const uint8_t *newValue, unsigned newLength)
String toString() const

Return a string representation of the session ID.

struct Options

Configurable options.

Public Functions

Options()
String toString() const

Public Members

bool sessionResume

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

bool clientAuthentication
bool verifyLater

Allow handshake to complete before verifying certificate.

bool freeKeyCertAfterHandshake
enum 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:

Default = 0

Let SSL implementation decide.

B512

512 bytes

K1

1024 bytes

K2
K4
K8
K16