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 Ssl::Alert

Alert codes defined by the standard.

See

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

Values:

Invalid = -1

Not an alert code.

XX

Classes

class Factory

Implemented by SSL adapter.

See

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 Value

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

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

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

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

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

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

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

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

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 Value

  • Certificate*: Returns NULL if there is no certificate available

size_t printTo(Print &p) const

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 Value

  • Alert: Alert::INVALID if not an alert