diff --git a/docs/html/_s_s_l_client_8h_source.html b/docs/html/_s_s_l_client_8h_source.html index f30fb5d..ca4b889 100644 --- a/docs/html/_s_s_l_client_8h_source.html +++ b/docs/html/_s_s_l_client_8h_source.html @@ -91,52 +91,52 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h_source.html','');});
SSLClient.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 "Client.h"
22 #include "SSLClientImpl.h"
23 #include "SSLSession.h"
24 #include "SSLClientParameters.h"
25 #include "SSLObj.h"
26 
27 #ifndef SSLClient_H_
28 #define SSLClient_H_
29 
35 template <class C, size_t SessionCache = 1>
36 class SSLClient : public SSLClientImpl {
37 /*
38  * static checks
39  * I'm a java developer, so I want to ensure that my inheritance is safe.
40  * These checks ensure that all the functions we use on class C are
41  * actually present on class C. It does this by checking that the
42  * class inherits from Client.
43  *
44  * Additionally, I ran into a lot of memory issues with large sessions caches.
45  * Since each session contains at max 352 bytes of memory, they eat of the
46  * stack quite quickly and can cause overflows. As a result, I have added a
47  * warning here to discourage the use of more than 3 sessions at a time. Any
48  * amount past that will require special modification of this library, and
49  * assumes you know what you are doing.
50  */
51 static_assert(SessionCache > 0 && SessionCache < 255, "There can be no less than one and no more than 255 sessions in the cache!");
52 static_assert(SessionCache <= 3, "You need to decrease the size of m_iobuf in order to have more than 3 sessions at once, otherwise memory issues will occur.");
53 
54 public:
72  explicit SSLClient( const C& client,
73  const br_x509_trust_anchor *trust_anchors,
74  const size_t trust_anchors_num,
75  const int analog_pin,
76  const DebugLevel debug = SSL_WARN)
77  : SSLClientImpl(trust_anchors, trust_anchors_num, analog_pin, debug)
78  , m_client(client)
79  , m_sessions{}
80  {
81  // set the timeout to a reasonable number (it can always be changes later)
82  // SSL Connections take a really long time so we don't want to time out a legitimate thing
83  setTimeout(30 * 1000);
84  }
85 
86  //========================================
87  //= Functions implemented in SSLClientImpl
88  //========================================
89 
129  int connect(IPAddress ip, uint16_t port) override { return connect_impl(ip, port); }
130 
167  int connect(const char *host, uint16_t port) override { return connect_impl(host, port); }
168 
170  size_t write(uint8_t b) override { return write_impl(&b, 1); }
194  size_t write(const uint8_t *buf, size_t size) override { return write_impl(buf, size); }
195 
214  int available() override { return available_impl(); }
215 
220  int read() override { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
242  int read(uint8_t *buf, size_t size) override { return read_impl(buf, size); }
243 
252  int peek() override { return peek_impl(); }
253 
261  void flush() override { return flush_impl(); }
262 
271  void stop() override { return stop_impl(); }
272 
286  uint8_t connected() override { return connected_impl(); }
287 
288  //========================================
289  //= Functions Not in the Client Interface
290  //========================================
291 
297  void setMutualAuthParams(const SSLClientParameters* params) { return set_mutual_impl(params); }
298 
313  SSLSession& getSession(const char* host, const IPAddress& addr) { return get_session_impl(host, addr); }
314 
323  void removeSession(const char* host, const IPAddress& addr) { return remove_session_impl(host, addr); }
324 
330  size_t getSessionCount() const override { return SessionCache; }
331 
337  operator bool() { return connected() > 0; }
339  bool operator==(const bool value) { return bool() == value; }
341  bool operator!=(const bool value) { return bool() != value; }
343  bool operator==(const C& rhs) { return m_client == rhs; }
345  bool operator!=(const C& rhs) { return m_client != rhs; }
347  uint16_t localPort() override { return m_client.localPort(); }
349  IPAddress remoteIP() override { return m_client.remoteIP(); }
351  uint16_t remotePort() override { return m_client.remotePort(); }
352 
354  C& getClient() { return m_client; }
355 
356 protected:
358  Client& get_arduino_client() override { return m_client; }
359  const Client& get_arduino_client() const override { return m_client; }
361  SSLSession* get_session_array() override { return m_sessions; }
362  const SSLSession* get_session_array() const override { return m_sessions; }
363 
364 private:
365  // create a copy of the client
366  C m_client;
367  // also store an array of SSLSessions, so we can resume communication with multiple websites
368  SSLSession m_sessions[SessionCache];
369 };
370 
371 #endif
SSLClient::setMutualAuthParams
void setMutualAuthParams(const SSLClientParameters *params)
Add a client certificate and enable support for mutual auth.
Definition: SSLClient.h:297
+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 "Client.h"
22 #include "SSLClientImpl.h"
23 #include "SSLSession.h"
24 #include "SSLClientParameters.h"
25 #include "SSLObj.h"
26 
27 #ifndef SSLClient_H_
28 #define SSLClient_H_
29 
35 template <class C, size_t SessionCache = 1>
36 class SSLClient : public SSLClientImpl {
37 /*
38  * static checks
39  * I'm a java developer, so I want to ensure that my inheritance is safe.
40  * These checks ensure that all the functions we use on class C are
41  * actually present on class C. It does this by checking that the
42  * class inherits from Client.
43  *
44  * Additionally, I ran into a lot of memory issues with large sessions caches.
45  * Since each session contains at max 352 bytes of memory, they eat of the
46  * stack quite quickly and can cause overflows. As a result, I have added a
47  * warning here to discourage the use of more than 3 sessions at a time. Any
48  * amount past that will require special modification of this library, and
49  * assumes you know what you are doing.
50  */
51 static_assert(SessionCache > 0 && SessionCache < 255, "There can be no less than one and no more than 255 sessions in the cache!");
52 static_assert(SessionCache <= 3, "You need to decrease the size of m_iobuf in order to have more than 3 sessions at once, otherwise memory issues will occur.");
53 
54 public:
72  explicit SSLClient( const C& client,
73  const br_x509_trust_anchor *trust_anchors,
74  const size_t trust_anchors_num,
75  const int analog_pin,
76  const DebugLevel debug = SSL_WARN)
77  : SSLClientImpl(trust_anchors, trust_anchors_num, analog_pin, debug)
78  , m_client(client)
79  , m_sessions{}
80  {
81  // set the timeout to a reasonable number (it can always be changes later)
82  // SSL Connections take a really long time so we don't want to time out a legitimate thing
83  setTimeout(30 * 1000);
84  }
85 
86  //========================================
87  //= Functions implemented in SSLClientImpl
88  //========================================
89 
129  int connect(IPAddress ip, uint16_t port) override { return connect_impl(ip, port); }
130 
167  int connect(const char *host, uint16_t port) override { return connect_impl(host, port); }
168 
170  size_t write(uint8_t b) override { return write_impl(&b, 1); }
194  size_t write(const uint8_t *buf, size_t size) override { return write_impl(buf, size); }
195 
214  int available() override { return available_impl(); }
215 
220  int read() override { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
242  int read(uint8_t *buf, size_t size) override { return read_impl(buf, size); }
243 
252  int peek() override { return peek_impl(); }
253 
261  void flush() override { return flush_impl(); }
262 
271  void stop() override { return stop_impl(); }
272 
286  uint8_t connected() override { return connected_impl(); }
287 
288  //========================================
289  //= Functions Not in the Client Interface
290  //========================================
291 
300  void setMutualAuthParams(const SSLClientParameters* params) { return set_mutual_impl(params); }
301 
316  SSLSession& getSession(const char* host, const IPAddress& addr) { return get_session_impl(host, addr); }
317 
326  void removeSession(const char* host, const IPAddress& addr) { return remove_session_impl(host, addr); }
327 
333  size_t getSessionCount() const override { return SessionCache; }
334 
340  operator bool() { return connected() > 0; }
342  bool operator==(const bool value) { return bool() == value; }
344  bool operator!=(const bool value) { return bool() != value; }
346  bool operator==(const C& rhs) { return m_client == rhs; }
348  bool operator!=(const C& rhs) { return m_client != rhs; }
350  uint16_t localPort() override { return m_client.localPort(); }
352  IPAddress remoteIP() override { return m_client.remoteIP(); }
354  uint16_t remotePort() override { return m_client.remotePort(); }
355 
357  C& getClient() { return m_client; }
358 
359 protected:
361  Client& get_arduino_client() override { return m_client; }
362  const Client& get_arduino_client() const override { return m_client; }
364  SSLSession* get_session_array() override { return m_sessions; }
365  const SSLSession* get_session_array() const override { return m_sessions; }
366 
367 private:
368  // create a copy of the client
369  C m_client;
370  // also store an array of SSLSessions, so we can resume communication with multiple websites
371  SSLSession m_sessions[SessionCache];
372 };
373 
374 #endif
SSLClient::setMutualAuthParams
void setMutualAuthParams(const SSLClientParameters *params)
Add a client certificate and enable support for mutual auth.
Definition: SSLClient.h:300
SSLClientImpl::write_impl
size_t write_impl(const uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:130
-
SSLClient::get_session_array
const SSLSession * get_session_array() const override
Definition: SSLClient.h:362
-
SSLClient::remoteIP
IPAddress remoteIP() override
Returns the remote IP, if C::remoteIP exists.
Definition: SSLClient.h:349
+
SSLClient::get_session_array
const SSLSession * get_session_array() const override
Definition: SSLClient.h:365
+
SSLClient::remoteIP
IPAddress remoteIP() override
Returns the remote IP, if C::remoteIP exists.
Definition: SSLClient.h:352
SSLClient::write
size_t write(uint8_t b) override
Definition: SSLClient.h:170
SSL_WARN
Definition: SSLClientImpl.h:66
SSLClientImpl::get_session_impl
SSLSession & get_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:286
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:345
+
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:348
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:214
-
SSLClient::getClient
C & getClient()
Returns a reference to the client object stored in this class. Take care not to break it.
Definition: SSLClient.h:354
+
SSLClient::getClient
C & getClient()
Returns a reference to the client object stored in this class. Take care not to break it.
Definition: SSLClient.h:357
SSLClientImpl::peek_impl
int peek_impl()
Definition: SSLClientImpl.cpp:209
SSLClientParameters
This struct stores data required for SSLClient to use mutual authentication.
Definition: SSLClientParameters.h:52
SSLClient::flush
void flush() override
Force writing the buffered bytes from SSLClient::write to the network.
Definition: SSLClient.h:261
SSLClient
The main SSLClient class. Check out README.md for more info.
Definition: SSLClient.h:36
-
SSLClient::operator!=
bool operator!=(const bool value)
Definition: SSLClient.h:341
+
SSLClient::operator!=
bool operator!=(const bool value)
Definition: SSLClient.h:344
SSLClient::stop
void stop() override
Close the connection.
Definition: SSLClient.h:271
SSLClient::write
size_t write(const uint8_t *buf, size_t size) override
Write some bytes to the SSL connection.
Definition: SSLClient.h:194
SSLClient::SSLClient
SSLClient(const C &client, const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug=SSL_WARN)
Initialize SSLClient with all of the prerequisites needed.
Definition: SSLClient.h:72
SSLClient::peek
int peek() override
View the first byte of the buffer, without removing it from the SSLClient Buffer.
Definition: SSLClient.h:252
SSLClientImpl::available_impl
int available_impl()
Definition: SSLClientImpl.cpp:173
-
SSLClient::operator==
bool operator==(const C &rhs)
Returns whether or not two SSLClient objects have the same underlying client object.
Definition: SSLClient.h:343
+
SSLClient::operator==
bool operator==(const C &rhs)
Returns whether or not two SSLClient objects have the same underlying client object.
Definition: SSLClient.h:346
SSLClientImpl::read_impl
int read_impl(uint8_t *buf, size_t size)
Definition: SSLClientImpl.cpp:194
-
SSLClient::get_session_array
SSLSession * get_session_array() override
Returns an instance of the session array that is on the stack.
Definition: SSLClient.h:361
+
SSLClient::get_session_array
SSLSession * get_session_array() override
Returns an instance of the session array that is on the stack.
Definition: SSLClient.h:364
SSLClientImpl::remove_session_impl
void remove_session_impl(const char *host, const IPAddress &addr)
Definition: SSLClientImpl.cpp:305
-
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:358
-
SSLClient::localPort
uint16_t localPort() override
Returns the local port, if C::localPort exists.
Definition: SSLClient.h:347
+
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:361
+
SSLClient::localPort
uint16_t localPort() override
Returns the local port, if C::localPort exists.
Definition: SSLClient.h:350
SSLClientImpl.h
SSLClientImpl::set_mutual_impl
void set_mutual_impl(const SSLClientParameters *params)
Definition: SSLClientImpl.cpp:316
SSLClient::read
int read() override
Read a single byte, or -1 if none is available.
Definition: SSLClient.h:220
SSLClientParameters.h
SSLClient::connected
uint8_t connected() override
Check if the device is connected.
Definition: SSLClient.h:286
SSLSession.h
-
SSLClient::get_arduino_client
const Client & get_arduino_client() const override
Definition: SSLClient.h:359
+
SSLClient::get_arduino_client
const Client & get_arduino_client() const override
Definition: SSLClient.h:362
SSLClient::connect
int connect(const char *host, uint16_t port) override
Connect over SSL to a host specified by a hostname.
Definition: SSLClient.h:167
-
SSLClient::operator==
bool operator==(const bool value)
Definition: SSLClient.h:339
-
SSLClient::remotePort
uint16_t remotePort() override
Returns the remote port, if C::remotePort exists. Else return 0.
Definition: SSLClient.h:351
+
SSLClient::operator==
bool operator==(const bool value)
Definition: SSLClient.h:342
+
SSLClient::remotePort
uint16_t remotePort() override
Returns the remote port, if C::remotePort exists. Else return 0.
Definition: SSLClient.h:354
SSLClientImpl::connect_impl
int connect_impl(IPAddress ip, uint16_t port)
Definition: SSLClientImpl.cpp:73
-
SSLClient::getSessionCount
size_t getSessionCount() const override
Get the maximum number of SSL sessions that can be stored at once.
Definition: SSLClient.h:330
+
SSLClient::getSessionCount
size_t getSessionCount() const override
Get the maximum number of SSL sessions that can be stored at once.
Definition: SSLClient.h:333
SSLClientImpl::stop_impl
void stop_impl()
Definition: SSLClientImpl.cpp:227
SSLClientImpl::flush_impl
void flush_impl()
Definition: SSLClientImpl.cpp:221
SSLObj.h
SSLClientImpl
Implementation code to be inherited by SSLClient.
Definition: SSLClientImpl.h:72
-
SSLClient::removeSession
void removeSession(const char *host, const IPAddress &addr)
Clear the session corresponding to a host and IP.
Definition: SSLClient.h:323
+
SSLClient::removeSession
void removeSession(const char *host, const IPAddress &addr)
Clear the session corresponding to a host and IP.
Definition: SSLClient.h:326
SSLClientImpl::connected_impl
uint8_t connected_impl()
Definition: SSLClientImpl.cpp:255
-
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:313
+
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:316
DebugLevel
DebugLevel
Level of verbosity used in logging for SSLClient.
Definition: SSLClientImpl.h:60
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:242
SSLClient::connect
int connect(IPAddress ip, uint16_t port) override
Connect over SSL to a host specified by an IP address.
Definition: SSLClient.h:129
diff --git a/docs/html/class_s_s_l_client.html b/docs/html/class_s_s_l_client.html index 66fcc3a..44b769d 100644 --- a/docs/html/class_s_s_l_client.html +++ b/docs/html/class_s_s_l_client.html @@ -1203,7 +1203,8 @@ template<class C , size_t SessionCache = 1>

Add a client certificate and enable support for mutual auth.

-

This function must be called BEFORE making an SSL connection.

+

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.
diff --git a/src/SSLClient.h b/src/SSLClient.h index 6116d61..6c635e1 100644 --- a/src/SSLClient.h +++ b/src/SSLClient.h @@ -292,7 +292,10 @@ public: /** * @brief Add a client certificate and enable support for mutual auth * - * This function must be called BEFORE making an SSL connection. + * Please ensure that the values in `params` are valid for the lifetime + * of SSLClient. You may want to make them global constants. + * + * @pre SSLClient has not already started an SSL connection. */ void setMutualAuthParams(const SSLClientParameters* params) { return set_mutual_impl(params); }