Session
-
class Ssl::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.
- Returns
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
- Returns
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.
- Returns
Connection* –
-
bool onConnect(tcp_pcb *tcp)
Handle connection event.
- Parameters
tcp –
- Returns
bool – true on success, false to abort the connection
-
inline bool isConnected() const
Determine if an SSL connection has been fully established.
- Returns
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
- Returns
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 –
- Returns
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
- Returns
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.
-
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.
-
inline const SessionId *getSessionId() const
-
struct Ssl::Options
Configurable options.
-
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:
-
enumerator Default
Let SSL implementation decide.
-
enumerator B512
512 bytes
-
enumerator K1
1024 bytes
-
enumerator K2
-
enumerator K4
-
enumerator K8
-
enumerator K16
-
enumerator Default