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
-
~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 sockettcp
: 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
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 dataoutput
: 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.
-
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.
-
-
struct
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:
-
Default
= 0¶ Let SSL implementation decide.
-
B512
¶ 512 bytes
-
K1
¶ 1024 bytes
-
K2
¶
-
K4
¶
-
K8
¶
-
K16
¶