# SSLClient: SSLClient.h Source File

SSLClient.h
Go to the documentation of this file.
/* Copyright 2019 OSU OPEnS Lab
*
* Permission is hereby granted, free of charge, to any person obtaining a copy of this
* software and associated documentation files (the "Software"), to deal in the Software
* without restriction, including without limitation the rights to use, copy, modify,
* merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
* permit persons to whom the Software is furnished to do so, subject to the following
* conditions:
*
* The above copyright notice and this permission notice shall be included in all
* copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
* INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
* PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
* HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
* OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
*/
#include "Client.h"
#include "SSLSession.h"
#include "SSLClientParameters.h"
#include "SSLObj.h"
#include <vector>
#ifndef SSLClient_H_
#define SSLClient_H_
class SSLClient : public Client {
public:
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
};
enum DebugLevel {
SSL_NONE = 0,
SSL_ERROR = 1,
SSL_WARN = 2,
SSL_INFO = 3,
};
explicit 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);
//========================================
//= Functions implemented in SSLClient.cpp
//========================================
int connect(IPAddress ip, uint16_t port) override;
int connect(const char *host, uint16_t port) override;
size_t write(const uint8_t *buf, size_t size) override;
size_t write(uint8_t b) override { return write(&b, 1); }
int available() override;
int read(uint8_t *buf, size_t size) override;
int read() override { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
int peek() override;
void flush() override;
void stop() override;
uint8_t connected() override;
//========================================
//= Functions Not in the Client Interface
//========================================
void setMutualAuthParams(const SSLClientParameters* params);
SSLSession* getSession(const char* host);
void removeSession(const char* host);
size_t getSessionCount() const { return m_sessions.size(); }
operator bool() { return connected() > 0; }
Client& getClient() { return m_client; }
void setTimeout(unsigned int t) { m_timeout = t; }
unsigned int getTimeout() const { return m_timeout; }
private:
Client& get_arduino_client() { return m_client; }
const Client& get_arduino_client() const { return m_client; }
bool m_soft_connected(const char* func_name);
int m_start_ssl(const char* host = nullptr, SSLSession* ssl_ses = nullptr);
int m_run_until(const unsigned target);
unsigned m_update_engine();
int m_get_session_index(const char* host) const;
void m_print_prefix(const char* func_name, const DebugLevel level) const;
void m_print_ssl_error(const int ssl_error, const DebugLevel level) const;
void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const;
template<typename T>
void m_print(const T str, const char* func_name, const DebugLevel level) const {
// check the current debug level and serial status
if (level > m_debug || !Serial) return;
// print prefix
m_print_prefix(func_name, level);
// print the message
Serial.println(str);
}
template<typename T>
void m_info(const T str, const char* func_name) const { m_print(str, func_name, SSL_INFO); }
template<typename T>
void m_warn(const T str, const char* func_name) const { m_print(str, func_name, SSL_WARN); }
template<typename T>
void m_error(const T str, const char* func_name) const { m_print(str, func_name, SSL_ERROR); }
//============================================
//= Data Members
//============================================
// create a reference the client
Client& m_client;
// also store an array of SSLSessions, so we can resume communication with multiple websites
std::vector<SSLSession> m_sessions;
// as well as the maximmum number of sessions we can store
const size_t m_max_sessions;
// store the pin to fetch an RNG see from
const int m_analog_pin;
// store whether to enable debug logging
const DebugLevel m_debug;
// store if we are connected in bearssl or not
bool m_is_connected;
// store the timeout for SSL internals
unsigned int m_timeout;
// store the context values required for SSL
br_ssl_client_context m_sslctx;
br_x509_minimal_context m_x509ctx;
// use a mono-directional buffer by default to cut memory in half
// can expand to a bi-directional buffer with maximum of BR_SSL_BUFSIZE_BIDI
// or shrink to below BR_SSL_BUFSIZE_MONO, and bearSSL will adapt automatically
// simply edit this value to change the buffer size to the desired value
// additionally, we need to correct buffer size based off of how many sessions we decide to cache
// since SSL takes so much memory if we don't it will cause the stack and heap to collide
unsigned char m_iobuf[2048];
// store the index of where we are writing in the buffer
// so we can send our records all at once to prevent
// weird timing issues
size_t m_write_idx;
};
#endif
SSLClient::connected
uint8_t connected() override
Check if the device is connected.
Definition: SSLClient.cpp:251
SSLClient::SSL_OUT_OF_MEMORY
Definition: SSLClient.h:58
SSLSession
This class stores values which allow SSLClient to save and resume SSL sessions.
Definition: SSLSession.h:51
SSLClient::setTimeout
void setTimeout(unsigned int t)
Set the timeout when waiting for an SSL response.
Definition: SSLClient.h:365
SSLClient::SSL_CLIENT_CONNECT_FAIL
Definition: SSLClient.h:48
SSLClient::SSL_INFO
Definition: SSLClient.h:75
SSLClient::SSL_BR_WRITE_ERROR
Definition: SSLClient.h:54
SSLClient::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)
Initialize SSLClient with all of the prerequisites needed.
Definition: SSLClient.cpp:55
SSLClient::flush
void flush() override
Force writing the buffered bytes from SSLClient::write to the network.
Definition: SSLClient.cpp:218
SSLClient::getSession
SSLSession * getSession(const char *host)
Gets a session reference corresponding to a host and IP, or a reference to a empty session if none ex...
Definition: SSLClient.cpp:282
SSLClientParameters
This struct stores data required for SSLClient to use mutual authentication.
Definition: SSLClientParameters.h:52
SSLClient::setMutualAuthParams
void setMutualAuthParams(const SSLClientParameters *params)
Add a client certificate and enable support for mutual auth.
Definition: SSLClient.cpp:306
SSLClient::available
int available() override
Returns the number of bytes available to read from the data that has been received and decrypted.
Definition: SSLClient.cpp:170
SSLClient
The main SSLClient class. Check out README.md for more info.
Definition: SSLClient.h:35
SSLClient::SSL_WARN
Definition: SSLClient.h:73
SSLClient::stop
void stop() override
Close the connection.
Definition: SSLClient.cpp:224
SSLClient::SSL_ERROR
Definition: SSLClient.h:71
SSLClient::connect
int connect(IPAddress ip, uint16_t port) override
Connect over SSL to a host specified by an IP address.
Definition: SSLClient.cpp:82
SSLClient::write
size_t write(const uint8_t *buf, size_t size) override
Write some bytes to the SSL connection.
Definition: SSLClient.cpp:127
SSLClient::read
int read() override
Read a single byte, or -1 if none is available.
Definition: SSLClient.h:258
SSLClient::Error
Error
Static constants defining the possible errors encountered.
Definition: SSLClient.h:45
SSLClient::SSL_CLIENT_WRTIE_ERROR
Definition: SSLClient.h:52
SSLClient::DebugLevel
DebugLevel
Level of verbosity used in logging for SSLClient.
Definition: SSLClient.h:67
SSLClient::getSessionCount
size_t getSessionCount() const
Get the maximum number of SSL sessions that can be stored at once.
Definition: SSLClient.h:349
SSLClient::peek
int peek() override
View the first byte of the buffer, without removing it from the SSLClient Buffer.
Definition: SSLClient.cpp:206
SSLClientParameters.h
SSLClient::SSL_BR_CONNECT_FAIL
Definition: SSLClient.h:50
SSLSession.h
SSLClient::write
size_t write(uint8_t b) override
Definition: SSLClient.h:210
SSLClient::getClient
Client & getClient()
Returns a reference to the client object stored in this class. Take care not to break it.
Definition: SSLClient.h:359
SSLClient::removeSession
void removeSession(const char *host)
Clear the session corresponding to a host and IP.
Definition: SSLClient.cpp:295
SSLClient::getTimeout
unsigned int getTimeout() const
Get the timeout when waiting for an SSL response.
Definition: SSLClient.h:371
SSLObj.h
SSLClient::SSL_NONE
Definition: SSLClient.h:69
SSLClient::SSL_OK
Definition: SSLClient.h:46
SSLClient::SSL_INTERNAL_ERROR
Definition: SSLClient.h:56