SSLClient  v1.6.9
SSLClient Class Reference

The main SSLClient class. Check out README.md for more info. More...

#include <SSLClient.h>

Inheritance diagram for SSLClient:

Public Types

enum  Error {
  SSL_OK = 0, SSL_CLIENT_CONNECT_FAIL = 2, SSL_BR_CONNECT_FAIL = 3, SSL_CLIENT_WRTIE_ERROR = 4,
  SSL_BR_WRITE_ERROR = 5, SSL_INTERNAL_ERROR = 6, SSL_OUT_OF_MEMORY = 7
}
 Static constants defining the possible errors encountered. More...
 
enum  DebugLevel {
  SSL_NONE = 0, SSL_ERROR = 1, SSL_WARN = 2, SSL_INFO = 3,
  SSL_DUMP = 4
}
 Level of verbosity used in logging for SSLClient. More...
 

Public Member Functions

 SSLClient (Client &client, const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const size_t max_sessions=1, const DebugLevel debug=SSL_WARN)
 Initialize SSLClient with all of the prerequisites needed. More...
 
int connect (IPAddress ip, uint16_t port) override
 Connect over SSL to a host specified by an IP address. More...
 
int connect (const char *host, uint16_t port) override
 Connect over SSL to a host specified by a hostname. More...
 
size_t write (const uint8_t *buf, size_t size) override
 Write some bytes to the SSL connection. More...
 
size_t write (uint8_t b) override
 
int available () override
 Returns the number of bytes available to read from the data that has been received and decrypted. More...
 
int read (uint8_t *buf, size_t size) override
 Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes read. More...
 
int read () override
 Read a single byte, or -1 if none is available. More...
 
int peek () override
 View the first byte of the buffer, without removing it from the SSLClient Buffer. More...
 
void flush () override
 Force writing the buffered bytes from SSLClient::write to the network. More...
 
void stop () override
 Close the connection. More...
 
uint8_t connected () override
 Check if the device is connected. More...
 
void setMutualAuthParams (const SSLClientParameters &params)
 Add a client certificate and enable support for mutual auth. More...
 
SSLSessiongetSession (const char *host)
 Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist. More...
 
void removeSession (const char *host)
 Clear the session corresponding to a host and IP. More...
 
size_t getSessionCount () const
 Get the maximum number of SSL sessions that can be stored at once. More...
 
 operator bool ()
 Equivalent to SSLClient::connected() > 0. More...
 
Client & getClient ()
 Returns a reference to the client object stored in this class. Take care not to break it. More...
 
void setTimeout (unsigned int t)
 Set the timeout when waiting for an SSL response. More...
 
unsigned int getTimeout () const
 Get the timeout when waiting for an SSL response. More...
 
void setVerificationTime (uint32_t days, uint32_t seconds)
 Change the time used during x509 verification to a different value. More...
 

Detailed Description

The main SSLClient class. Check out README.md for more info.

Member Enumeration Documentation

Level of verbosity used in logging for SSLClient.

Use these values when initializing SSLClient to set how many logs you would like to see in the Serial monitor.

Enumerator
SSL_NONE 

No logging output

SSL_ERROR 

Only output errors that result in connection failure

SSL_WARN 

Output errors and warnings (useful when just starting to develop)

SSL_INFO 

Output errors, warnings, and internal information (very verbose)

SSL_DUMP 

In addition to the above logs, dumps every byte in SSLClient::write to the Serial monitor

Static constants defining the possible errors encountered.

If SSLClient encounters an error, it will generally output logs into the serial monitor. If you need a way of programmatically checking the errors, you can do so with SSLClient::getWriteError(), which will return one of these values.

Enumerator
SSL_OK 
SSL_CLIENT_CONNECT_FAIL 

The underlying client failed to connect, probably not an issue with SSL

SSL_BR_CONNECT_FAIL 

BearSSL failed to complete the SSL handshake, check logs for bear ssl error output

SSL_CLIENT_WRTIE_ERROR 

The underlying client failed to write a payload, probably not an issue with SSL

SSL_BR_WRITE_ERROR 

An internal error occurred with BearSSL, check logs for diagnosis.

SSL_INTERNAL_ERROR 

An internal error occurred with SSLClient, and you probably need to submit an issue on Github.

SSL_OUT_OF_MEMORY 

SSLClient detected that there was not enough memory (>8000 bytes) to continue.

Constructor & Destructor Documentation

SSLClient::SSLClient ( Client &  client,
const br_x509_trust_anchor *  trust_anchors,
const size_t  trust_anchors_num,
const int  analog_pin,
const size_t  max_sessions = 1,
const DebugLevel  debug = SSL_WARN 
)
explicit

Initialize SSLClient with all of the prerequisites needed.

Precondition
You will need to generate an array of trust_anchors (root certificates) based off of the domains you want to make SSL connections to. Check out the TrustAnchors.md file for more info.
The analog_pin should be set to input.
Parameters
clientThe base network device to create an SSL socket on. This object will be copied and the copy will be stored in SSLClient.
trust_anchorsTrust anchors used in the verification of the SSL server certificate. Check out TrustAnchors.md for more info.
trust_anchors_numThe number of objects in the trust_anchors array.
analog_pinAn analog pin to pull random bytes from, used in seeding the RNG.
max_sessionsThe maximum number of SSL sessions to store connection information from.
debugThe level of debug logging (use the ::DebugLevel enum).

Member Function Documentation

int SSLClient::available ( )
override

Returns the number of bytes available to read from the data that has been received and decrypted.

This function updates the state of the SSL engine (including writing any data, see SSLClient::write) and as a result should be called periodically when expecting data. Additionally, since if there are no bytes and if SSLClient::connected is false this function returns zero (this same behavior is found in EthernetClient), it is prudent to ensure in your own code that the preconditions are met before checking this function to prevent an ambiguous result.

The implementation for this function can be found in SSLClientImpl::available

Precondition
SSLClient::connected must be true. (Call SSLClient::connected before this function)
Returns
The number of bytes available (can be zero), or zero if any of the pre conditions aren't satisfied.
int SSLClient::connect ( IPAddress  ip,
uint16_t  port 
)
override

Connect over SSL to a host specified by an IP address.

SSLClient::connect(host, port) should be preferred over this function, as verifying the domain name is a step in ensuring the certificate is legitimate, which is important to the security of the device. Additionally, SSL sessions cannot be resumed when using this function, which can drastically increase initial connect time.

This function initializes the socket by calling m_client::connect(IPAddress, uint16_t) with the parameters supplied, then once the socket is open, uses BearSSL to to complete a SSL handshake. Due to the design of the SSL standard, this function will probably take an extended period (1-4sec) to negotiate the handshake and finish the connection. This function runs until the SSL handshake succeeds or fails.

SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so SSLClient uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.

The implementation for this function can be found in SSLClientImpl::connect_impl(IPAddress, uint16_t).

Precondition
The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP.
SSLClient can only have one connection at a time, so the client object must not already be connected.
There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, SSLClient will fail).
There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out TrustAnchors.md .
Parameters
ipThe IP address to connect to
portthe port to connect to
Returns
1 if success, 0 if failure
int SSLClient::connect ( const char *  host,
uint16_t  port 
)
override

Connect over SSL to a host specified by a hostname.

This function initializes the socket by calling m_client::connect(const char*, uint16_t) with the parameters supplied, then once the socket is open, uses BearSSL to complete a SSL handshake. This function runs until the SSL handshake succeeds or fails.

SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so SSLClient uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.

This function will usually take around 4-10 seconds. If possible, this function also attempts to resume the SSL session if one is present matching the hostname string, which will reduce connection time to 100-500ms. To read more about this functionality, check out Session Caching in the README.

The implementation for this function can be found in SSLClientImpl::connect_impl(const char*, uint16_t)

Precondition
The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP.
SSLClient can only have one connection at a time, so the client object must not already be connected.
There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, SSLClient will fail).
There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out TrustAnchors.md .
Parameters
hostThe hostname as a null-terminated c-string ("www.google.com")
portThe port to connect to on the host (443 for HTTPS)
Returns
1 of success, 0 if failure
uint8_t SSLClient::connected ( )
override

Check if the device is connected.

Use this function to determine if SSLClient is still connected and a SSL connection is active. It should be noted that this function should be called before SSLClient::available– both functions send and receive data with the SSLClient::m_client device, however SSLClient::available has some delays built in to protect SSLClient::m_client from being polled too frequently, and SSLClient::connected contains logic to ensure that if the socket is dropped SSLClient will react accordingly.

The implementation for this function can be found in SSLClientImpl::connected_impl.

Returns
1 if connected, 0 if not
void SSLClient::flush ( )
override

Force writing the buffered bytes from SSLClient::write to the network.

This function is blocking until all bytes from the buffer are written. For an explanation of how writing with SSLClient works, please see SSLClient::write. The implementation for this function can be found in SSLClientImpl::flush.

Client& SSLClient::getClient ( )
inline

Returns a reference to the client object stored in this class. Take care not to break it.

SSLSession * SSLClient::getSession ( const char *  host)

Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist.

If no session corresponding to the host and IP exist, then this function will cycle through sessions in a rotating order. This allows the session cache to continually store sessions, however it will also result in old sessions being cleared and returned. In general, it is a good idea to use a SessionCache size equal to the number of domains you plan on connecting to.

The implementation for this function can be found at SSLClientImpl::get_session_impl.

Parameters
hostA hostname c string, or NULL if one is not available
addrAn IP address
Returns
A pointer to the SSLSession, or NULL of none matched the criteria available
size_t SSLClient::getSessionCount ( ) const
inline

Get the maximum number of SSL sessions that can be stored at once.

Returns
The SessionCache template parameter.
unsigned int SSLClient::getTimeout ( ) const
inline

Get the timeout when waiting for an SSL response.

Returns
The timeout value in milliseconds.
SSLClient::operator bool ( )
inline

Equivalent to SSLClient::connected() > 0.

Returns
true if connected, false if not
int SSLClient::peek ( )
override

View the first byte of the buffer, without removing it from the SSLClient Buffer.

The implementation for this function can be found in SSLClientImpl::peek

Precondition
SSLClient::available must be >0
Returns
The first byte received, or -1 if the preconditions are not satisfied (warning: do not use if your data may be -1, as the return value is ambiguous)
int SSLClient::read ( uint8_t *  buf,
size_t  size 
)
override

Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes read.

This function checks if bytes are ready to be read by calling SSLClient::available, and if so copies size number of bytes from the IO buffer into the buf pointer. Data read using this function will not include any SSL or socket commands, as the Client and BearSSL will capture those and process them separately.

If you find that you are having a lot of timeout errors, SSLClient may be experiencing a buffer overflow. Checkout README.md for more information.

The implementation for this function can be found in SSLClientImpl::read_impl(uint8_t*, size_t)

Precondition
SSLClient::available must be >0
Parameters
bufThe pointer to the buffer to put SSL application data into
sizeThe size (in bytes) to copy to the buffer
Returns
The number of bytes copied (<= size), or -1 if the preconditions are not satisfied.
int SSLClient::read ( )
inlineoverride

Read a single byte, or -1 if none is available.

See also
SSLClient::read(uint8_t*, size_t)
void SSLClient::removeSession ( const char *  host)

Clear the session corresponding to a host and IP.

The implementation for this function can be found at SSLClientImpl::remove_session_impl.

Parameters
hostA hostname c string, or nullptr if one is not available
addrAn IP address
void SSLClient::setMutualAuthParams ( const SSLClientParameters params)

Add a client certificate and enable support for mutual auth.

Please ensure that the values in params are valid for the lifetime of SSLClient. You may want to make them global constants.

Precondition
SSLClient has not already started an SSL connection.
void SSLClient::setTimeout ( unsigned int  t)
inline

Set the timeout when waiting for an SSL response.

Parameters
tThe timeout value, in milliseconds (defaults to 30 seconds if not set). Do not set to zero.
void SSLClient::setVerificationTime ( uint32_t  days,
uint32_t  seconds 
)

Change the time used during x509 verification to a different value.

This function directly calls br_x509_minimal_set_time to change the validation time used by the minimal verification engine. You can use this function if the default value of the compile time is causing issues. See https://bearssl.org/apidoc/bearssl__x509_8h.html#a7f3558b1999ce904084d578700b1002c for more information what this function does and how to use it.

Parameters
daysDays are counted in a proleptic Gregorian calendar since January 1st, 0 AD.
secondsSeconds are counted since midnight, from 0 to 86400 (a count of 86400 is possible only if a leap second happened).
void SSLClient::stop ( )
override

Close the connection.

If the SSL session is still active, all incoming data is discarded and BearSSL will attempt to close the session gracefully (will write to the network), and then call m_client::stop. If the session is not active or an error was encountered previously, this function will simply call m_client::stop. The implementation for this function can be found in SSLClientImpl::peek.

size_t SSLClient::write ( const uint8_t *  buf,
size_t  size 
)
override

Write some bytes to the SSL connection.

Assuming all preconditions are met, this function writes data to the BearSSL IO buffer, BUT does not initially send the data. Instead, you must call SSLClient::available or SSLClient::flush, which will detect that the buffer is ready for writing, and will write the data to the network. Alternatively, if this function is requested to write a larger amount of data than SSLClientImpl::m_iobuf can handle, data will be written to the network in pages the size of SSLClientImpl::m_iobuf until all the data in buf is sent–attempting to keep all writes to the network grouped together. For information on why this is the case check out README.md .

The implementation for this function can be found in SSLClientImpl::write_impl(const uint8_t*, size_t)

Precondition
The socket and SSL layer must be connected, meaning SSLClient::connected must be true.
BearSSL must not be waiting for the recipt of user data (if it is, there is probably an error with how the protocol in implemented in your code).
Parameters
bufthe pointer to a buffer of bytes to copy
sizethe number of bytes to copy from the buffer
Returns
The number of bytes copied to the buffer (size), or zero if the BearSSL engine fails to become ready for writing data.
size_t SSLClient::write ( uint8_t  b)
inlineoverride
See also
SSLClient::write(uint8_t*, size_t)

The documentation for this class was generated from the following files: