SSL Adapter API

These classes provide the interface between a Ssl::Session and an appropriate adapter.

Error codes

Error codes are implementation specific, however 0 always indicates success and < 0 for error.

To obtain a description for an error code, use Ssl::Connection::getErrorString().

SSL Alerts are reported via error codes. To obtain the alert code call Ssl::Connection::getAlert() which returns an Ssl::Alert code. If the error code is not an alert then Alert::INVALID is returned.

enum class Ssl::Alert

Alert codes defined by the standard.

See also

See https://tools.ietf.org/html/rfc8446#page-85

Values:

enumerator Invalid

Not an alert code.

enumerator XX

Classes

class Factory

Implemented by SSL adapter.

See also

https://en.wikipedia.org/wiki/Factory_method_pattern

Public Functions

virtual Context *createContext(Session &session) = 0

Create SSL context that can be used to create new client or server connections.

Return values:

Context* – The constructed context, shouldn’t fail (except on OOM)

class Context

Implemented by SSL adapter to create and manage SSL connections.

Public Functions

virtual bool init() = 0

Initializer method that must be called after object creation and before the creation of server or client connections.

Return values:

bool – true on success

virtual Connection *createClient(tcp_pcb *tcp) = 0

Creates client SSL connection. Your SSL client use this call to create a client connection to remote server.

Return values:

Connection* –

virtual Connection *createServer(tcp_pcb *tcp) = 0

Creates server SSL connection. Your SSL servers use this call to allow remote clients to connect to them and use SSL.

Return values:

Connection* –

class Connection : public Printable

Implemented by SSL adapter to handle a connection.

Returned int error codes are 0 for success, or < 0 for error.

The error codes themselves are implementation-specific. Use getErrorString() to obtain the message. SSL Alerts are also reported via error codes and can be obtained using a call to getAlert().

Public Functions

virtual bool isHandshakeDone() const = 0

Checks if the handshake has finished.

Return values:

bool – true on success

virtual int read(InputBuffer &input, uint8_t *&output) = 0

Reads encrypted information and decrypts it.

Parameters:

• input – Source encrypted data

• output – Pointer to decrypted plaintext buffer

Return values:

0 – : handshake is still in progress > 0 : there is decrypted data < 0 : error

virtual int write(const uint8_t *data, size_t length) = 0

Converts and sends plaintext data.

Parameters:

• data –

• length –

Return values:

int – length of the data that was actually written < 0 on error

virtual CipherSuite getCipherSuite() const = 0

Gets the cipher suite that was used.

Return values:

CipherSuite – IDs as defined by SSL/TLS standard

virtual SessionId getSessionId() const = 0

Gets the current session id object. Should be called after handshake.

Return values:

SessionId –

virtual const Certificate *getCertificate() const = 0

Gets the certificate object. That object MUST be owned by the Connection implementation and should not be freed outside of it.

Return values:

Certificate* – Returns NULL if there is no certificate available

virtual size_t printTo(Print &p) const override

For debugging.

virtual String getErrorString(int error) const = 0

Get string for error code.

virtual Alert getAlert(int error) const = 0

Get alert code from error.

Parameters:

error –

Return values:

Alert – Alert::INVALID if not an alert