diff --git a/README.md b/README.md index 7f8051f..6eb75d8 100644 --- a/README.md +++ b/README.md @@ -133,7 +133,11 @@ If you need to clear a session, you can do so using the SSLSession::removeSessio Some ideas that didn't quite fit in the API documentation. ### SSLClient with Ethernet -If you are using the [Arduino Ethernet library](https://github.com/arduino-libraries/Ethernet), you will need to modify the library to support the large buffer sizes required by SSL (detailed in [resources](#resources)). To do this, first find the location of the library in the directory where Arduino is installed (`C:\Program Files (x86)\Arduino` on Windows). Inside of this directory, navigate to `libraries\Ethernet\src` (`C:\Program Files (x86)\Arduino\libraries\Ethernet\src` on Windows). Modify `Ethernet.h` to replace these lines: +If you are using the [Arduino Ethernet library](https://github.com/arduino-libraries/Ethernet), you will need to modify the library to support the large buffer sizes required by SSL (detailed in [resources](#resources)). You can either modify the library yourself, or use [this fork of the Ethernet library with the modification](https://github.com/OPEnSLab-OSU/EthernetLarge). To use the fork, simply install the library using the "add a .zip library" button in Arduino, and replace `#include "Ethernet.h"` with `#include "EthernetLarge.h"` in your sketch. Alternatively if for some reason this solution does not work, you can apply the modification using the instructions below. + +#### Manual Modification + + First find the location of the library in the directory where Arduino is installed (`C:\Program Files (x86)\Arduino` on Windows). Inside of this directory, navigate to `libraries\Ethernet\src` (`C:\Program Files (x86)\Arduino\libraries\Ethernet\src` on Windows). Modify `Ethernet.h` to replace these lines: ```C++ ... // Configure the maximum number of sockets to support. W5100 chips can have diff --git a/docs/html/_r_e_a_d_m_e_8md.html b/docs/html/_r_e_a_d_m_e_8md.html index 1db9a61..159a65b 100644 --- a/docs/html/_r_e_a_d_m_e_8md.html +++ b/docs/html/_r_e_a_d_m_e_8md.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_client_8h.html b/docs/html/_s_s_l_client_8h.html index 17512cf..ce1fe0c 100644 --- a/docs/html/_s_s_l_client_8h.html +++ b/docs/html/_s_s_l_client_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_client_8h_source.html b/docs/html/_s_s_l_client_8h_source.html index 9c2ad57..9ffa230 100644 --- a/docs/html/_s_s_l_client_8h_source.html +++ b/docs/html/_s_s_l_client_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
@@ -96,7 +96,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h_source.html','');});
SSLClient::remoteIP
IPAddress remoteIP() override
Returns the remote IP, if C::remoteIP exists. Else return INADDR_NONE.
Definition: SSLClient.h:343
SSLClient::write
size_t write(uint8_t b) override
Definition: SSLClient.h:165
SSL_WARN
Definition: SSLClientImpl.h:65
-
SSLClientImpl::get_session_impl
SSLSession & get_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:280
+
SSLClientImpl::get_session_impl
SSLSession & get_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:294
SSLSession
This class stores values which allow SSLClient to save and resume SSL sessions.
Definition: SSLSession.h:52
SSLClient::operator!=
bool operator!=(const C &rhs)
Returns whether or not two SSLClient objects do not have the same underlying client object.
Definition: SSLClient.h:333
SSLClient::available
int available() override
Returns the number of bytes available to read from the data that has been received and decrypted.
Definition: SSLClient.h:209
@@ -113,7 +113,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h_source.html','');});
SSLClient::operator==
bool operator==(const C &rhs)
Returns whether or not two SSLClient objects have the same underlying client object.
Definition: SSLClient.h:331
SSLClientImpl::read_impl
int read_impl(uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:196
SSLClient::get_session_array
SSLSession * get_session_array() override
Returns an instance of the session array that is on the stack.
Definition: SSLClient.h:367
-
SSLClientImpl::remove_session_impl
void remove_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:299
+
SSLClientImpl::remove_session_impl
void remove_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:313
SSLClient::get_arduino_client
Client & get_arduino_client() override
Returns an instance of m_client that is polymorphic and can be used by SSLClientImpl.
Definition: SSLClient.h:364
SSLClient::localPort
uint16_t localPort() override
Returns the local port, C::localPort exists. Else return 0.
Definition: SSLClient.h:335
SSLClientImpl.h
@@ -131,7 +131,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h_source.html','');});
SSLClientImpl::flush_impl
void flush_impl()
Definition: SSLClientImpl.cpp:223
SSLClientImpl
Implementation code to be inherited by SSLClient.
Definition: SSLClientImpl.h:71
SSLClient::removeSession
void removeSession(const char *host, const IPAddress &addr)
Clear the session corresponding to a host and IP.
Definition: SSLClient.h:311
-
SSLClientImpl::connected_impl
uint8_t connected_impl()
Definition: SSLClientImpl.cpp:254
+
SSLClientImpl::connected_impl
uint8_t connected_impl()
Definition: SSLClientImpl.cpp:263
SSLClient::getSession
SSLSession & getSession(const char *host, const IPAddress &addr)
Gets a session reference corresponding to a host and IP, or a reference to a empty session if none ex...
Definition: SSLClient.h:301
DebugLevel
DebugLevel
Level of verbosity used in logging for SSLClient.
Definition: SSLClientImpl.h:59
SSLClient::read
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 re...
Definition: SSLClient.h:237
diff --git a/docs/html/_s_s_l_client_impl_8cpp.html b/docs/html/_s_s_l_client_impl_8cpp.html index 96141e4..07e3d3b 100644 --- a/docs/html/_s_s_l_client_impl_8cpp.html +++ b/docs/html/_s_s_l_client_impl_8cpp.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_client_impl_8h.html b/docs/html/_s_s_l_client_impl_8h.html index 505dabd..0acd8c1 100644 --- a/docs/html/_s_s_l_client_impl_8h.html +++ b/docs/html/_s_s_l_client_impl_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_client_impl_8h_source.html b/docs/html/_s_s_l_client_impl_8h_source.html index 1b5e56e..6bd981b 100644 --- a/docs/html/_s_s_l_client_impl_8h_source.html +++ b/docs/html/_s_s_l_client_impl_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
@@ -91,12 +91,12 @@ $(document).ready(function(){initNavTree('_s_s_l_client_impl_8h_source.html','')
SSLClientImpl.h
-Go to the documentation of this file.
1 /* Copyright 2019 OSU OPEnS Lab
2  *
3  * Permission is hereby granted, free of charge, to any person obtaining a copy of this
4  * software and associated documentation files (the "Software"), to deal in the Software
5  * without restriction, including without limitation the rights to use, copy, modify,
6  * merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
7  * permit persons to whom the Software is furnished to do so, subject to the following
8  * conditions:
9  *
10  * The above copyright notice and this permission notice shall be included in all
11  * copies or substantial portions of the Software.
12  *
13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
14  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
15  * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
16  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
17  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
18  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
19  */
20 
21 #include "bearssl.h"
22 #include "Arduino.h"
23 #include "Client.h"
24 #include "SSLSession.h"
25 
26 #ifndef SSLClientImpl_H_
27 #define SSLClientImpl_H_
28 
37 enum Error {
38  SSL_OK = 0,
40  SSL_CLIENT_CONNECT_FAIL,
42  SSL_BR_CONNECT_FAIL,
44  SSL_CLIENT_WRTIE_ERROR,
46  SSL_BR_WRITE_ERROR,
48  SSL_INTERNAL_ERROR,
50  SSL_OUT_OF_MEMORY
51 };
52 
59 enum DebugLevel {
61  SSL_NONE = 0,
63  SSL_ERROR = 1,
65  SSL_WARN = 2,
67  SSL_INFO = 3,
68 };
69 
71 class SSLClientImpl : public Client {
72 public:
74  explicit SSLClientImpl(const br_x509_trust_anchor *trust_anchors,
75  const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug);
76 
77  //============================================
78  //= Functions implemented in SSLClientImpl.cpp
79  //============================================
80 
82  int connect_impl(IPAddress ip, uint16_t port);
84  int connect_impl(const char *host, uint16_t port);
86  size_t write_impl(const uint8_t *buf, size_t size);
88  int available_impl();
90  int read_impl(uint8_t *buf, size_t size);
92  int peek_impl();
94  void flush_impl();
96  void stop_impl();
98  uint8_t connected_impl();
100  SSLSession& get_session_impl(const char* host, const IPAddress& addr);
102  void remove_session_impl(const char* host, const IPAddress& addr);
103 
104  //============================================
105  //= Functions implemented in SSLClient.h
106  //============================================
108  virtual uint16_t localPort() = 0;
110  virtual IPAddress remoteIP() = 0;
112  virtual uint16_t remotePort() = 0;
114  virtual size_t getSessionCount() const = 0;
115 
116 protected:
118  virtual Client& get_arduino_client() = 0;
119  virtual const Client& get_arduino_client() const = 0;
121  virtual SSLSession* get_session_array() = 0;
122  virtual const SSLSession* get_session_array() const = 0;
123 
124  //============================================
125  //= Functions implemented in SSLClientImpl.cpp
126  //============================================
127 
129  void m_print_prefix(const char* func_name, const DebugLevel level) const;
130 
132  void m_print_ssl_error(const int ssl_error, const DebugLevel level) const;
133 
135  void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const;
136 
138  template<typename T>
139  void m_print(const T str, const char* func_name, const DebugLevel level) const {
140  // check the current debug level and serial status
141  if (level > m_debug || !Serial) return;
142  // print prefix
143  m_print_prefix(func_name, level);
144  // print the message
145  Serial.println(str);
146  }
147 
149  template<typename T>
150  void m_info(const T str, const char* func_name) const { m_print(str, func_name, SSL_INFO); }
151 
152  template<typename T>
153  void m_warn(const T str, const char* func_name) const { m_print(str, func_name, SSL_WARN); }
154 
155  template<typename T>
156  void m_error(const T str, const char* func_name) const { m_print(str, func_name, SSL_ERROR); }
157 
158 private:
160  bool m_soft_connected(const char* func_name);
162  int m_start_ssl(const char* host, SSLSession& ssl_ses);
164  int m_run_until(const unsigned target);
166  unsigned m_update_engine();
168  int m_get_session_index(const char* host, const IPAddress& addr) const;
169 
170  //============================================
171  //= Data Members
172  //============================================
173 
174  // store pointers to the trust anchors
175  // should not be computed at runtime
176  const br_x509_trust_anchor *m_trust_anchors;
177  const size_t m_trust_anchors_num;
178  // store the pin to fetch an RNG see from
179  const int m_analog_pin;
180  // store an index of where a new session can be placed if we don't have any corresponding sessions
181  size_t m_session_index;
182  // store whether to enable debug logging
183  const DebugLevel m_debug;
184  // store if we are connected in bearssl or not
185  bool m_is_connected;
186  // store the context values required for SSL
187  br_ssl_client_context m_sslctx;
188  br_x509_minimal_context m_x509ctx;
189  // use a mono-directional buffer by default to cut memory in half
190  // can expand to a bi-directional buffer with maximum of BR_SSL_BUFSIZE_BIDI
191  // or shrink to below BR_SSL_BUFSIZE_MONO, and bearSSL will adapt automatically
192  // simply edit this value to change the buffer size to the desired value
193  // additionally, we need to correct buffer size based off of how many sessions we decide to cache
194  // since SSL takes so much memory if we don't it will cause the stack and heap to collide
202  unsigned char m_iobuf[BR_SSL_BUFSIZE_MONO / 4];
203  static_assert(sizeof m_iobuf <= BR_SSL_BUFSIZE_BIDI, "m_iobuf must be below maximum buffer size");
204  // store the index of where we are writing in the buffer
205  // so we can send our records all at once to prevent
206  // weird timing issues
207  size_t m_write_idx;
208 };
209 
210 #endif /* SSLClientImpl_H_ */
SSLClientImpl::write_impl
size_t write_impl(const uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:132
+Go to the documentation of this file.
1 /* Copyright 2019 OSU OPEnS Lab
2  *
3  * Permission is hereby granted, free of charge, to any person obtaining a copy of this
4  * software and associated documentation files (the "Software"), to deal in the Software
5  * without restriction, including without limitation the rights to use, copy, modify,
6  * merge, publish, distribute, sublicense, and/or sell copies of the Software, and to
7  * permit persons to whom the Software is furnished to do so, subject to the following
8  * conditions:
9  *
10  * The above copyright notice and this permission notice shall be included in all
11  * copies or substantial portions of the Software.
12  *
13  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
14  * INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A
15  * PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
16  * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
17  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
18  * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
19  */
20 
21 #include "bearssl.h"
22 #include "Arduino.h"
23 #include "Client.h"
24 #include "SSLSession.h"
25 
26 #ifndef SSLClientImpl_H_
27 #define SSLClientImpl_H_
28 
37 enum Error {
38  SSL_OK = 0,
40  SSL_CLIENT_CONNECT_FAIL,
42  SSL_BR_CONNECT_FAIL,
44  SSL_CLIENT_WRTIE_ERROR,
46  SSL_BR_WRITE_ERROR,
48  SSL_INTERNAL_ERROR,
50  SSL_OUT_OF_MEMORY
51 };
52 
59 enum DebugLevel {
61  SSL_NONE = 0,
63  SSL_ERROR = 1,
65  SSL_WARN = 2,
67  SSL_INFO = 3,
68 };
69 
71 class SSLClientImpl : public Client {
72 public:
74  explicit SSLClientImpl(const br_x509_trust_anchor *trust_anchors,
75  const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug);
76 
77  //============================================
78  //= Functions implemented in SSLClientImpl.cpp
79  //============================================
80 
82  int connect_impl(IPAddress ip, uint16_t port);
84  int connect_impl(const char *host, uint16_t port);
86  size_t write_impl(const uint8_t *buf, size_t size);
88  int available_impl();
90  int read_impl(uint8_t *buf, size_t size);
92  int peek_impl();
94  void flush_impl();
96  void stop_impl();
98  uint8_t connected_impl();
100  SSLSession& get_session_impl(const char* host, const IPAddress& addr);
102  void remove_session_impl(const char* host, const IPAddress& addr);
103 
104  //============================================
105  //= Functions implemented in SSLClient.h
106  //============================================
108  virtual uint16_t localPort() = 0;
110  virtual IPAddress remoteIP() = 0;
112  virtual uint16_t remotePort() = 0;
114  virtual size_t getSessionCount() const = 0;
115 
116 protected:
118  virtual Client& get_arduino_client() = 0;
119  virtual const Client& get_arduino_client() const = 0;
121  virtual SSLSession* get_session_array() = 0;
122  virtual const SSLSession* get_session_array() const = 0;
123 
124  //============================================
125  //= Functions implemented in SSLClientImpl.cpp
126  //============================================
127 
129  void m_print_prefix(const char* func_name, const DebugLevel level) const;
130 
132  void m_print_ssl_error(const int ssl_error, const DebugLevel level) const;
133 
135  void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const;
136 
138  template<typename T>
139  void m_print(const T str, const char* func_name, const DebugLevel level) const {
140  // check the current debug level and serial status
141  if (level > m_debug || !Serial) return;
142  // print prefix
143  m_print_prefix(func_name, level);
144  // print the message
145  Serial.println(str);
146  }
147 
149  template<typename T>
150  void m_info(const T str, const char* func_name) const { m_print(str, func_name, SSL_INFO); }
151 
152  template<typename T>
153  void m_warn(const T str, const char* func_name) const { m_print(str, func_name, SSL_WARN); }
154 
155  template<typename T>
156  void m_error(const T str, const char* func_name) const { m_print(str, func_name, SSL_ERROR); }
157 
158 private:
160  bool m_soft_connected(const char* func_name);
162  int m_start_ssl(const char* host, SSLSession& ssl_ses);
164  int m_run_until(const unsigned target);
166  unsigned m_update_engine();
168  int m_get_session_index(const char* host, const IPAddress& addr) const;
169 
170  //============================================
171  //= Data Members
172  //============================================
173 
174  // store pointers to the trust anchors
175  // should not be computed at runtime
176  const br_x509_trust_anchor *m_trust_anchors;
177  const size_t m_trust_anchors_num;
178  // store the pin to fetch an RNG see from
179  const int m_analog_pin;
180  // store an index of where a new session can be placed if we don't have any corresponding sessions
181  size_t m_session_index;
182  // store whether to enable debug logging
183  const DebugLevel m_debug;
184  // store if we are connected in bearssl or not
185  bool m_is_connected;
186  // store the context values required for SSL
187  br_ssl_client_context m_sslctx;
188  br_x509_minimal_context m_x509ctx;
189  // use a mono-directional buffer by default to cut memory in half
190  // can expand to a bi-directional buffer with maximum of BR_SSL_BUFSIZE_BIDI
191  // or shrink to below BR_SSL_BUFSIZE_MONO, and bearSSL will adapt automatically
192  // simply edit this value to change the buffer size to the desired value
193  // additionally, we need to correct buffer size based off of how many sessions we decide to cache
194  // since SSL takes so much memory if we don't it will cause the stack and heap to collide
202  unsigned char m_iobuf[BR_SSL_BUFSIZE_MONO / 8];
203  static_assert(sizeof m_iobuf <= BR_SSL_BUFSIZE_BIDI, "m_iobuf must be below maximum buffer size");
204  // store the index of where we are writing in the buffer
205  // so we can send our records all at once to prevent
206  // weird timing issues
207  size_t m_write_idx;
208 };
209 
210 #endif /* SSLClientImpl_H_ */
SSLClientImpl::write_impl
size_t write_impl(const uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:132
SSLClientImpl::remotePort
virtual uint16_t remotePort()=0
SSLClientImpl::m_print
void m_print(const T str, const char *func_name, const DebugLevel level) const
debugging print function, only prints if m_debug is true
Definition: SSLClientImpl.h:139
SSL_WARN
Definition: SSLClientImpl.h:65
SSLClientImpl::remoteIP
virtual IPAddress remoteIP()=0
-
SSLClientImpl::get_session_impl
SSLSession & get_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:280
+
SSLClientImpl::get_session_impl
SSLSession & get_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:294
SSLSession
This class stores values which allow SSLClient to save and resume SSL sessions.
Definition: SSLSession.h:52
SSLClientImpl::m_info
void m_info(const T str, const char *func_name) const
Prints a info message to serial, if info messages are enabled.
Definition: SSLClientImpl.h:150
SSLClientImpl::SSLClientImpl
SSLClientImpl(const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug)
Definition: SSLClientImpl.cpp:53
@@ -109,18 +109,18 @@ $(document).ready(function(){initNavTree('_s_s_l_client_impl_8h_source.html','')
SSLClientImpl::get_session_array
virtual SSLSession * get_session_array()=0
SSL_BR_WRITE_ERROR
Definition: SSLClientImpl.h:46
SSL_OK
Definition: SSLClientImpl.h:38
-
SSLClientImpl::m_print_ssl_error
void m_print_ssl_error(const int ssl_error, const DebugLevel level) const
Prints the string associated with a write error.
Definition: SSLClientImpl.cpp:654
+
SSLClientImpl::m_print_ssl_error
void m_print_ssl_error(const int ssl_error, const DebugLevel level) const
Prints the string associated with a write error.
Definition: SSLClientImpl.cpp:657
SSLClientImpl::available_impl
int available_impl()
Definition: SSLClientImpl.cpp:175
Error
Error
Static constants defining the possible errors encountered.
Definition: SSLClientImpl.h:37
SSL_BR_CONNECT_FAIL
Definition: SSLClientImpl.h:42
SSLClientImpl::read_impl
int read_impl(uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:196
-
SSLClientImpl::remove_session_impl
void remove_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:299
+
SSLClientImpl::remove_session_impl
void remove_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:313
SSL_CLIENT_WRTIE_ERROR
Definition: SSLClientImpl.h:44
SSLClientImpl::get_arduino_client
virtual Client & get_arduino_client()=0
SSL_CLIENT_CONNECT_FAIL
Definition: SSLClientImpl.h:40
-
SSLClientImpl::m_print_prefix
void m_print_prefix(const char *func_name, const DebugLevel level) const
Prints a debugging prefix to all logs, so we can attatch them to useful information.
Definition: SSLClientImpl.cpp:636
+
SSLClientImpl::m_print_prefix
void m_print_prefix(const char *func_name, const DebugLevel level) const
Prints a debugging prefix to all logs, so we can attatch them to useful information.
Definition: SSLClientImpl.cpp:639
SSL_NONE
Definition: SSLClientImpl.h:61
-
SSLClientImpl::m_print_br_error
void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const
Print the text string associated with a BearSSL error code.
Definition: SSLClientImpl.cpp:669
+
SSLClientImpl::m_print_br_error
void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const
Print the text string associated with a BearSSL error code.
Definition: SSLClientImpl.cpp:672
SSLClientImpl::m_warn
void m_warn(const T str, const char *func_name) const
Definition: SSLClientImpl.h:153
SSLSession.h
SSLClientImpl::connect_impl
int connect_impl(IPAddress ip, uint16_t port)
Definition: SSLClientImpl.cpp:75
@@ -129,7 +129,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_impl_8h_source.html','')
SSLClientImpl::flush_impl
void flush_impl()
Definition: SSLClientImpl.cpp:223
SSLClientImpl
Implementation code to be inherited by SSLClient.
Definition: SSLClientImpl.h:71
SSLClientImpl::localPort
virtual uint16_t localPort()=0
-
SSLClientImpl::connected_impl
uint8_t connected_impl()
Definition: SSLClientImpl.cpp:254
+
SSLClientImpl::connected_impl
uint8_t connected_impl()
Definition: SSLClientImpl.cpp:263
DebugLevel
DebugLevel
Level of verbosity used in logging for SSLClient.
Definition: SSLClientImpl.h:59
diff --git a/docs/html/_s_s_l_session_8cpp.html b/docs/html/_s_s_l_session_8cpp.html index 5a05643..458ced1 100644 --- a/docs/html/_s_s_l_session_8cpp.html +++ b/docs/html/_s_s_l_session_8cpp.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_session_8h.html b/docs/html/_s_s_l_session_8h.html index 9f37a1c..7f71f53 100644 --- a/docs/html/_s_s_l_session_8h.html +++ b/docs/html/_s_s_l_session_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_s_s_l_session_8h_source.html b/docs/html/_s_s_l_session_8h_source.html index 9cee101..2a0f814 100644 --- a/docs/html/_s_s_l_session_8h_source.html +++ b/docs/html/_s_s_l_session_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_t_l_s12__only__profile_8c.html b/docs/html/_t_l_s12__only__profile_8c.html index 3df9e79..0562e86 100644 --- a/docs/html/_t_l_s12__only__profile_8c.html +++ b/docs/html/_t_l_s12__only__profile_8c.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/_trust_anchors_8md.html b/docs/html/_trust_anchors_8md.html index 1bcd811..e73745c 100644 --- a/docs/html/_trust_anchors_8md.html +++ b/docs/html/_trust_anchors_8md.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/annotated.html b/docs/html/annotated.html index 5f354c0..10791df 100644 --- a/docs/html/annotated.html +++ b/docs/html/annotated.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/cert_8h.html b/docs/html/cert_8h.html index c4a0e50..9bb5578 100644 --- a/docs/html/cert_8h.html +++ b/docs/html/cert_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/cert_8h_source.html b/docs/html/cert_8h_source.html index aa6730c..e1db8ed 100644 --- a/docs/html/cert_8h_source.html +++ b/docs/html/cert_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_client-members.html b/docs/html/class_s_s_l_client-members.html index d196482..b0199db 100644 --- a/docs/html/class_s_s_l_client-members.html +++ b/docs/html/class_s_s_l_client-members.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_client.html b/docs/html/class_s_s_l_client.html index 364ee42..00e645b 100644 --- a/docs/html/class_s_s_l_client.html +++ b/docs/html/class_s_s_l_client.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_client_impl-members.html b/docs/html/class_s_s_l_client_impl-members.html index 49c0e58..62d86a9 100644 --- a/docs/html/class_s_s_l_client_impl-members.html +++ b/docs/html/class_s_s_l_client_impl-members.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_client_impl.html b/docs/html/class_s_s_l_client_impl.html index 244b09f..0cb6b98 100644 --- a/docs/html/class_s_s_l_client_impl.html +++ b/docs/html/class_s_s_l_client_impl.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_session-members.html b/docs/html/class_s_s_l_session-members.html index b854c41..79365b7 100644 --- a/docs/html/class_s_s_l_session-members.html +++ b/docs/html/class_s_s_l_session-members.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/class_s_s_l_session.html b/docs/html/class_s_s_l_session.html index adb0e30..777e8e2 100644 --- a/docs/html/class_s_s_l_session.html +++ b/docs/html/class_s_s_l_session.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/classes.html b/docs/html/classes.html index 2fe6ffe..8bd69a7 100644 --- a/docs/html/classes.html +++ b/docs/html/classes.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html b/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html index 125fbda..e1f45cd 100644 --- a/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html +++ b/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/dir_68267d1309a1af8e8297ef4c3efbcdba.html b/docs/html/dir_68267d1309a1af8e8297ef4c3efbcdba.html index 05e7cd3..c2517de 100644 --- a/docs/html/dir_68267d1309a1af8e8297ef4c3efbcdba.html +++ b/docs/html/dir_68267d1309a1af8e8297ef4c3efbcdba.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/dir_9c42dc81377249a918256dbb9cfb2167.html b/docs/html/dir_9c42dc81377249a918256dbb9cfb2167.html index 36b29ce..0f6fe49 100644 --- a/docs/html/dir_9c42dc81377249a918256dbb9cfb2167.html +++ b/docs/html/dir_9c42dc81377249a918256dbb9cfb2167.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/dir_d28a4824dc47e487b107a5db32ef43c4.html b/docs/html/dir_d28a4824dc47e487b107a5db32ef43c4.html index 46d074e..d7796f8 100644 --- a/docs/html/dir_d28a4824dc47e487b107a5db32ef43c4.html +++ b/docs/html/dir_d28a4824dc47e487b107a5db32ef43c4.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/dir_dfc5a9f91fbfb9426c406a3f10131a54.html b/docs/html/dir_dfc5a9f91fbfb9426c406a3f10131a54.html index deb9b96..e955a0c 100644 --- a/docs/html/dir_dfc5a9f91fbfb9426c406a3f10131a54.html +++ b/docs/html/dir_dfc5a9f91fbfb9426c406a3f10131a54.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/files.html b/docs/html/files.html index 5be5ad7..dac1fdb 100644 --- a/docs/html/files.html +++ b/docs/html/files.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/functions.html b/docs/html/functions.html index dea6a9f..fe84459 100644 --- a/docs/html/functions.html +++ b/docs/html/functions.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/functions_func.html b/docs/html/functions_func.html index 3a214ff..9d99958 100644 --- a/docs/html/functions_func.html +++ b/docs/html/functions_func.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals.html b/docs/html/globals.html index 06ac476..2125a13 100644 --- a/docs/html/globals.html +++ b/docs/html/globals.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals_defs.html b/docs/html/globals_defs.html index 29e9042..110a147 100644 --- a/docs/html/globals_defs.html +++ b/docs/html/globals_defs.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals_enum.html b/docs/html/globals_enum.html index 9ddaa5f..44a509d 100644 --- a/docs/html/globals_enum.html +++ b/docs/html/globals_enum.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals_eval.html b/docs/html/globals_eval.html index eae7b57..ea1f9be 100644 --- a/docs/html/globals_eval.html +++ b/docs/html/globals_eval.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals_func.html b/docs/html/globals_func.html index ecab3f9..bb7f1cb 100644 --- a/docs/html/globals_func.html +++ b/docs/html/globals_func.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/globals_vars.html b/docs/html/globals_vars.html index 99e9fff..4c696ff 100644 --- a/docs/html/globals_vars.html +++ b/docs/html/globals_vars.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/hierarchy.html b/docs/html/hierarchy.html index 7ad10b4..7595b1b 100644 --- a/docs/html/hierarchy.html +++ b/docs/html/hierarchy.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/index.html b/docs/html/index.html index d1a4668..104e104 100644 --- a/docs/html/index.html +++ b/docs/html/index.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
@@ -138,7 +138,9 @@ $(document).ready(function(){initNavTree('index.html','');});

Implementation Gotchas

Some ideas that didn't quite fit in the API documentation.

SSLClient with Ethernet

-

If you are using the Arduino Ethernet library, you will need to modify the library to support the large buffer sizes required by SSL (detailed in resources). To do this, first find the location of the library in the directory where Arduino is installed (C:\Program Files (x86)\Arduino on Windows). Inside of this directory, navigate to libraries\Ethernet\src (C:\Program Files (x86)\Arduino\libraries\Ethernet\src on Windows). Modify Ethernet.h to replace these lines:

{C++}
...
// Configure the maximum number of sockets to support. W5100 chips can have
// up to 4 sockets. W5200 & W5500 can have up to 8 sockets. Several bytes
// of RAM are used for each socket. Reducing the maximum can save RAM, but
// you are limited to fewer simultaneous connections.
#if defined(RAMEND) && defined(RAMSTART) && ((RAMEND - RAMSTART) <= 2048)
#define MAX_SOCK_NUM 4
#else
#define MAX_SOCK_NUM 8
#endif
// By default, each socket uses 2K buffers inside the Wiznet chip. If
// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting
// this will use larger buffers within the Wiznet chip. Large buffers
// can really help with UDP protocols like Artnet. In theory larger
// buffers should allow faster TCP over high-latency links, but this
// does not always seem to work in practice (maybe Wiznet bugs?)
//#define ETHERNET_LARGE_BUFFERS
...

With this:

{C++}
...
// Configure the maximum number of sockets to support. W5100 chips can have
// up to 4 sockets. W5200 & W5500 can have up to 8 sockets. Several bytes
// of RAM are used for each socket. Reducing the maximum can save RAM, but
// you are limited to fewer simultaneous connections.
#define MAX_SOCK_NUM 2
// By default, each socket uses 2K buffers inside the Wiznet chip. If
// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting
// this will use larger buffers within the Wiznet chip. Large buffers
// can really help with UDP protocols like Artnet. In theory larger
// buffers should allow faster TCP over high-latency links, but this
// does not always seem to work in practice (maybe Wiznet bugs?)
#define ETHERNET_LARGE_BUFFERS
...

You may need to use sudo or administrator permissions to make this modification. We change MAX_SOCK_NUM and ETHERNET_LARGE_BUFFERS so the Ethernet hardware can allocate a larger space for SSLClient, however a downside of this modification is we are now only able to have two sockets concurrently. As most microprocessors barely have enough memory for one SSL connection, this limitation will rarely be encountered in practice.

+

If you are using the Arduino Ethernet library, you will need to modify the library to support the large buffer sizes required by SSL (detailed in resources). You can either modify the library yourself, or use this fork of the Ethernet library with the modification. To use the fork, simply install the library using the "add a .zip library" button in Arduino, and replace #include "Ethernet.h" with #include "EthernetLarge.h" in your sketch. Alternatively if for some reason this solution does not work, you can apply the modification using the instructions below.

+

Manual Modification

+

First find the location of the library in the directory where Arduino is installed (C:\Program Files (x86)\Arduino on Windows). Inside of this directory, navigate to libraries\Ethernet\src (C:\Program Files (x86)\Arduino\libraries\Ethernet\src on Windows). Modify Ethernet.h to replace these lines:

{C++}
...
// Configure the maximum number of sockets to support. W5100 chips can have
// up to 4 sockets. W5200 & W5500 can have up to 8 sockets. Several bytes
// of RAM are used for each socket. Reducing the maximum can save RAM, but
// you are limited to fewer simultaneous connections.
#if defined(RAMEND) && defined(RAMSTART) && ((RAMEND - RAMSTART) <= 2048)
#define MAX_SOCK_NUM 4
#else
#define MAX_SOCK_NUM 8
#endif
// By default, each socket uses 2K buffers inside the Wiznet chip. If
// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting
// this will use larger buffers within the Wiznet chip. Large buffers
// can really help with UDP protocols like Artnet. In theory larger
// buffers should allow faster TCP over high-latency links, but this
// does not always seem to work in practice (maybe Wiznet bugs?)
//#define ETHERNET_LARGE_BUFFERS
...

With this:

{C++}
...
// Configure the maximum number of sockets to support. W5100 chips can have
// up to 4 sockets. W5200 & W5500 can have up to 8 sockets. Several bytes
// of RAM are used for each socket. Reducing the maximum can save RAM, but
// you are limited to fewer simultaneous connections.
#define MAX_SOCK_NUM 2
// By default, each socket uses 2K buffers inside the Wiznet chip. If
// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting
// this will use larger buffers within the Wiznet chip. Large buffers
// can really help with UDP protocols like Artnet. In theory larger
// buffers should allow faster TCP over high-latency links, but this
// does not always seem to work in practice (maybe Wiznet bugs?)
#define ETHERNET_LARGE_BUFFERS
...

You may need to use sudo or administrator permissions to make this modification. We change MAX_SOCK_NUM and ETHERNET_LARGE_BUFFERS so the Ethernet hardware can allocate a larger space for SSLClient, however a downside of this modification is we are now only able to have two sockets concurrently. As most microprocessors barely have enough memory for one SSL connection, this limitation will rarely be encountered in practice.

Random Data

The SSL protocol requires that SSLClient generate some random bits before connecting with a server. BearSSL provides a random number generator but requires a some entropy for a seed. Normally this seed is generated by taking the microsecond time using the internal clock, however since most microcontrollers are not build with this feature another source must be found. As a simple solution, SSLClient uses a floating analog pin as an external source of random data, passed through to the constructor in the analog_pin argument. Before every connection, SSLClient will take the bottom byte from 16 analog reads on analog_pin, and combine these bytes into a 16 byte random number, which is used as a seed for BearSSL. To ensure the most random data, it is recommended that this analog pin be either floating or connected to a location not modifiable by the microcontroller (i.e. a battery voltage readout).

Certificate Verification

diff --git a/docs/html/md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html b/docs/html/md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html index 960a2fb..8ea9d13 100644 --- a/docs/html/md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html +++ b/docs/html/md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/pages.html b/docs/html/pages.html index c715a5c..40f7260 100644 --- a/docs/html/pages.html +++ b/docs/html/pages.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/time__macros_8h.html b/docs/html/time__macros_8h.html index 896b8b7..e7f6961 100644 --- a/docs/html/time__macros_8h.html +++ b/docs/html/time__macros_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/time__macros_8h_source.html b/docs/html/time__macros_8h_source.html index 653873a..38aa464 100644 --- a/docs/html/time__macros_8h_source.html +++ b/docs/html/time__macros_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/trust__anchors_8h.html b/docs/html/trust__anchors_8h.html index a9424eb..9256c2b 100644 --- a/docs/html/trust__anchors_8h.html +++ b/docs/html/trust__anchors_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/trust__anchors_8h_source.html b/docs/html/trust__anchors_8h_source.html index bb93808..05a0dbe 100644 --- a/docs/html/trust__anchors_8h_source.html +++ b/docs/html/trust__anchors_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/trustanchors_8h.html b/docs/html/trustanchors_8h.html index 5c6825e..72d7454 100644 --- a/docs/html/trustanchors_8h.html +++ b/docs/html/trustanchors_8h.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/docs/html/trustanchors_8h_source.html b/docs/html/trustanchors_8h_source.html index d5a8043..c21f425 100644 --- a/docs/html/trustanchors_8h_source.html +++ b/docs/html/trustanchors_8h_source.html @@ -30,7 +30,7 @@
SSLClient -  1.0 +  v1.1.1
Add TLS 1.2 functionality to any network library.
diff --git a/examples/EthernetHTTPS/EthernetHTTPS.ino b/examples/EthernetHTTPS/EthernetHTTPS.ino index fd7416c..5245554 100644 --- a/examples/EthernetHTTPS/EthernetHTTPS.ino +++ b/examples/EthernetHTTPS/EthernetHTTPS.ino @@ -14,11 +14,11 @@ */ - // NOTE: The Ethernet library MUST be modified to use this example! - // For more detailed instructions check out https://github.com/OPEnSLab-OSU/SSLClient#sslclient-with-ethernet + // NOTE: This example REQUIRES the EthernetLarge library. + // You can get it here: https://github.com/OPEnSLab-OSU/EthernetLarge #include -#include +#include #include #include "trust_anchors.h" diff --git a/examples/EthernetMultiHTTPS/EthernetMultiHTTPS.ino b/examples/EthernetMultiHTTPS/EthernetMultiHTTPS.ino index debc697..e21f0b1 100644 --- a/examples/EthernetMultiHTTPS/EthernetMultiHTTPS.ino +++ b/examples/EthernetMultiHTTPS/EthernetMultiHTTPS.ino @@ -15,11 +15,11 @@ */ - // NOTE: The Ethernet library MUST be modified to use this example! - // For more detailed instructions check out https://github.com/OPEnSLab-OSU/SSLClient#sslclient-with-ethernet + // NOTE: This example REQUIRES the EthernetLarge library. + // You can get it here: https://github.com/OPEnSLab-OSU/EthernetLarge #include -#include +#include #include #include "trustanchors.h" // Enter a MAC address for your controller below. diff --git a/library.properties b/library.properties index 3dbb486..a625705 100644 --- a/library.properties +++ b/library.properties @@ -1,5 +1,5 @@ name=SSLClient -version=1.1 +version=1.1.1 author=Noah Koontz maintainer=OPEnS Lab sentence=Arduino library to add SSL functionality to any Client class