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