diff --git a/docs/_s_s_l_client_8h.html b/docs/_s_s_l_client_8h.html index 133e125..97708dd 100644 --- a/docs/_s_s_l_client_8h.html +++ b/docs/_s_s_l_client_8h.html @@ -95,7 +95,6 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h.html','');});
#include "Client.h"
#include "SSLSession.h"
#include "SSLClientParameters.h"
-#include "SSLObj.h"
#include <vector>

Go to the source code of this file.

diff --git a/docs/_s_s_l_client_8h_source.html b/docs/_s_s_l_client_8h_source.html index 4982c56..743f269 100644 --- a/docs/_s_s_l_client_8h_source.html +++ b/docs/_s_s_l_client_8h_source.html @@ -90,42 +90,41 @@ $(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 "SSLSession.h"
23 #include "SSLClientParameters.h"
24 #include "SSLObj.h"
25 #include <vector>
26 
27 #ifndef SSLClient_H_
28 #define SSLClient_H_
29 
35 class SSLClient : public Client {
36 public:
45  enum Error {
46  SSL_OK = 0,
48  SSL_CLIENT_CONNECT_FAIL = 2,
50  SSL_BR_CONNECT_FAIL = 3,
52  SSL_CLIENT_WRTIE_ERROR = 4,
54  SSL_BR_WRITE_ERROR = 5,
56  SSL_INTERNAL_ERROR = 6,
58  SSL_OUT_OF_MEMORY = 7
59  };
60 
67  enum DebugLevel {
69  SSL_NONE = 0,
71  SSL_ERROR = 1,
73  SSL_WARN = 2,
75  SSL_INFO = 3,
76  };
77 
95  explicit SSLClient( Client& client,
96  const br_x509_trust_anchor *trust_anchors,
97  const size_t trust_anchors_num,
98  const int analog_pin,
99  const size_t max_sessions = 1,
100  const DebugLevel debug = SSL_WARN);
101 
102  //========================================
103  //= Functions implemented in SSLClient.cpp
104  //========================================
105 
145  int connect(IPAddress ip, uint16_t port) override;
146 
183  int connect(const char *host, uint16_t port) override;
184 
208  size_t write(const uint8_t *buf, size_t size) override;
210  size_t write(uint8_t b) override { return write(&b, 1); }
211 
230  int available() override;
231 
253  int read(uint8_t *buf, size_t size) override;
258  int read() override { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
259 
268  int peek() override;
269 
277  void flush() override;
278 
287  void stop() override;
288 
302  uint8_t connected() override;
303 
304  //========================================
305  //= Functions Not in the Client Interface
306  //========================================
307 
316  void setMutualAuthParams(const SSLClientParameters* params);
317 
332  SSLSession* getSession(const char* host);
333 
342  void removeSession(const char* host);
343 
349  size_t getSessionCount() const { return m_sessions.size(); }
350 
356  operator bool() { return connected() > 0; }
357 
359  Client& getClient() { return m_client; }
360 
365  void setTimeout(unsigned int t) { m_timeout = t; }
366 
371  unsigned int getTimeout() const { return m_timeout; }
372 
373 private:
375  Client& get_arduino_client() { return m_client; }
376  const Client& get_arduino_client() const { return m_client; }
377 
379  bool m_soft_connected(const char* func_name);
381  int m_start_ssl(const char* host = nullptr, SSLSession* ssl_ses = nullptr);
383  int m_run_until(const unsigned target);
385  unsigned m_update_engine();
387  int m_get_session_index(const char* host) const;
388 
390  void m_print_prefix(const char* func_name, const DebugLevel level) const;
391 
393  void m_print_ssl_error(const int ssl_error, const DebugLevel level) const;
394 
396  void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const;
397 
399  template<typename T>
400  void m_print(const T str, const char* func_name, const DebugLevel level) const {
401  // check the current debug level and serial status
402  if (level > m_debug || !Serial) return;
403  // print prefix
404  m_print_prefix(func_name, level);
405  // print the message
406  Serial.println(str);
407  }
408 
410  template<typename T>
411  void m_info(const T str, const char* func_name) const { m_print(str, func_name, SSL_INFO); }
412 
413  template<typename T>
414  void m_warn(const T str, const char* func_name) const { m_print(str, func_name, SSL_WARN); }
415 
416  template<typename T>
417  void m_error(const T str, const char* func_name) const { m_print(str, func_name, SSL_ERROR); }
418 
419  //============================================
420  //= Data Members
421  //============================================
422  // create a reference the client
423  Client& m_client;
424  // also store an array of SSLSessions, so we can resume communication with multiple websites
425  std::vector<SSLSession> m_sessions;
426  // as well as the maximmum number of sessions we can store
427  const size_t m_max_sessions;
428  // store the pin to fetch an RNG see from
429  const int m_analog_pin;
430  // store whether to enable debug logging
431  const DebugLevel m_debug;
432  // store if we are connected in bearssl or not
433  bool m_is_connected;
434  // store the timeout for SSL internals
435  unsigned int m_timeout;
436  // store the context values required for SSL
437  br_ssl_client_context m_sslctx;
438  br_x509_minimal_context m_x509ctx;
439  // use a mono-directional buffer by default to cut memory in half
440  // can expand to a bi-directional buffer with maximum of BR_SSL_BUFSIZE_BIDI
441  // or shrink to below BR_SSL_BUFSIZE_MONO, and bearSSL will adapt automatically
442  // simply edit this value to change the buffer size to the desired value
443  // additionally, we need to correct buffer size based off of how many sessions we decide to cache
444  // since SSL takes so much memory if we don't it will cause the stack and heap to collide
452  unsigned char m_iobuf[2048];
453  // store the index of where we are writing in the buffer
454  // so we can send our records all at once to prevent
455  // weird timing issues
456  size_t m_write_idx;
457 };
458 
459 #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
+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 "SSLSession.h"
23 #include "SSLClientParameters.h"
24 #include <vector>
25 
26 #ifndef SSLClient_H_
27 #define SSLClient_H_
28 
34 class SSLClient : public Client {
35 public:
44  enum Error {
45  SSL_OK = 0,
47  SSL_CLIENT_CONNECT_FAIL = 2,
49  SSL_BR_CONNECT_FAIL = 3,
51  SSL_CLIENT_WRTIE_ERROR = 4,
53  SSL_BR_WRITE_ERROR = 5,
55  SSL_INTERNAL_ERROR = 6,
57  SSL_OUT_OF_MEMORY = 7
58  };
59 
66  enum DebugLevel {
68  SSL_NONE = 0,
70  SSL_ERROR = 1,
72  SSL_WARN = 2,
74  SSL_INFO = 3,
75  };
76 
94  explicit SSLClient( Client& client,
95  const br_x509_trust_anchor *trust_anchors,
96  const size_t trust_anchors_num,
97  const int analog_pin,
98  const size_t max_sessions = 1,
99  const DebugLevel debug = SSL_WARN);
100 
101  //========================================
102  //= Functions implemented in SSLClient.cpp
103  //========================================
104 
144  int connect(IPAddress ip, uint16_t port) override;
145 
182  int connect(const char *host, uint16_t port) override;
183 
207  size_t write(const uint8_t *buf, size_t size) override;
209  size_t write(uint8_t b) override { return write(&b, 1); }
210 
229  int available() override;
230 
252  int read(uint8_t *buf, size_t size) override;
257  int read() override { uint8_t read_val; return read(&read_val, 1) > 0 ? read_val : -1; };
258 
267  int peek() override;
268 
276  void flush() override;
277 
286  void stop() override;
287 
301  uint8_t connected() override;
302 
303  //========================================
304  //= Functions Not in the Client Interface
305  //========================================
306 
315  void setMutualAuthParams(const SSLClientParameters& params);
316 
331  SSLSession* getSession(const char* host);
332 
341  void removeSession(const char* host);
342 
348  size_t getSessionCount() const { return m_sessions.size(); }
349 
355  operator bool() { return connected() > 0; }
356 
358  Client& getClient() { return m_client; }
359 
364  void setTimeout(unsigned int t) { m_timeout = t; }
365 
370  unsigned int getTimeout() const { return m_timeout; }
371 
372 private:
374  Client& get_arduino_client() { return m_client; }
375  const Client& get_arduino_client() const { return m_client; }
376 
378  bool m_soft_connected(const char* func_name);
380  int m_start_ssl(const char* host = nullptr, SSLSession* ssl_ses = nullptr);
382  int m_run_until(const unsigned target);
384  unsigned m_update_engine();
386  int m_get_session_index(const char* host) const;
387 
389  void m_print_prefix(const char* func_name, const DebugLevel level) const;
390 
392  void m_print_ssl_error(const int ssl_error, const DebugLevel level) const;
393 
395  void m_print_br_error(const unsigned br_error_code, const DebugLevel level) const;
396 
398  template<typename T>
399  void m_print(const T str, const char* func_name, const DebugLevel level) const {
400  // check the current debug level and serial status
401  if (level > m_debug || !Serial) return;
402  // print prefix
403  m_print_prefix(func_name, level);
404  // print the message
405  Serial.println(str);
406  }
407 
409  template<typename T>
410  void m_info(const T str, const char* func_name) const { m_print(str, func_name, SSL_INFO); }
411 
412  template<typename T>
413  void m_warn(const T str, const char* func_name) const { m_print(str, func_name, SSL_WARN); }
414 
415  template<typename T>
416  void m_error(const T str, const char* func_name) const { m_print(str, func_name, SSL_ERROR); }
417 
418  //============================================
419  //= Data Members
420  //============================================
421  // create a reference the client
422  Client& m_client;
423  // also store an array of SSLSessions, so we can resume communication with multiple websites
424  std::vector<SSLSession> m_sessions;
425  // as well as the maximmum number of sessions we can store
426  const size_t m_max_sessions;
427  // store the pin to fetch an RNG see from
428  const int m_analog_pin;
429  // store whether to enable debug logging
430  const DebugLevel m_debug;
431  // store if we are connected in bearssl or not
432  bool m_is_connected;
433  // store the timeout for SSL internals
434  unsigned int m_timeout;
435  // store the context values required for SSL
436  br_ssl_client_context m_sslctx;
437  br_x509_minimal_context m_x509ctx;
438  // use a mono-directional buffer by default to cut memory in half
439  // can expand to a bi-directional buffer with maximum of BR_SSL_BUFSIZE_BIDI
440  // or shrink to below BR_SSL_BUFSIZE_MONO, and bearSSL will adapt automatically
441  // simply edit this value to change the buffer size to the desired value
442  // additionally, we need to correct buffer size based off of how many sessions we decide to cache
443  // since SSL takes so much memory if we don't it will cause the stack and heap to collide
451  unsigned char m_iobuf[2048];
452  // store the index of where we are writing in the buffer
453  // so we can send our records all at once to prevent
454  // weird timing issues
455  size_t m_write_idx;
456 };
457 
458 #endif
SSLClient::connected
uint8_t connected() override
Check if the device is connected.
Definition: SSLClient.cpp:220
+
SSLClient::SSL_OUT_OF_MEMORY
Definition: SSLClient.h:57
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
+
SSLClient::setTimeout
void setTimeout(unsigned int t)
Set the timeout when waiting for an SSL response.
Definition: SSLClient.h:364
+
SSLClient::SSL_CLIENT_CONNECT_FAIL
Definition: SSLClient.h:47
+
SSLClient::SSL_INFO
Definition: SSLClient.h:74
+
SSLClient::SSL_BR_WRITE_ERROR
Definition: SSLClient.h:53
+
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:24
+
SSLClient::flush
void flush() override
Force writing the buffered bytes from SSLClient::write to the network.
Definition: SSLClient.cpp:187
+
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:251
+
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:139
+
SSLClient
The main SSLClient class. Check out README.md for more info.
Definition: SSLClient.h:34
+
SSLClient::SSL_WARN
Definition: SSLClient.h:72
+
SSLClient::stop
void stop() override
Close the connection.
Definition: SSLClient.cpp:193
+
SSLClient::SSL_ERROR
Definition: SSLClient.h:70
+
SSLClient::connect
int connect(IPAddress ip, uint16_t port) override
Connect over SSL to a host specified by an IP address.
Definition: SSLClient.cpp:51
+
SSLClient::write
size_t write(const uint8_t *buf, size_t size) override
Write some bytes to the SSL connection.
Definition: SSLClient.cpp:96
+
SSLClient::read
int read() override
Read a single byte, or -1 if none is available.
Definition: SSLClient.h:257
+
SSLClient::setMutualAuthParams
void setMutualAuthParams(const SSLClientParameters &params)
Add a client certificate and enable support for mutual auth.
Definition: SSLClient.cpp:275
+
SSLClient::Error
Error
Static constants defining the possible errors encountered.
Definition: SSLClient.h:44
+
SSLClient::SSL_CLIENT_WRTIE_ERROR
Definition: SSLClient.h:51
+
SSLClient::DebugLevel
DebugLevel
Level of verbosity used in logging for SSLClient.
Definition: SSLClient.h:66
+
SSLClient::getSessionCount
size_t getSessionCount() const
Get the maximum number of SSL sessions that can be stored at once.
Definition: SSLClient.h:348
+
SSLClient::peek
int peek() override
View the first byte of the buffer, without removing it from the SSLClient Buffer.
Definition: SSLClient.cpp:175
SSLClientParameters.h
-
SSLClient::SSL_BR_CONNECT_FAIL
Definition: SSLClient.h:50
+
SSLClient::SSL_BR_CONNECT_FAIL
Definition: SSLClient.h:49
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
+
SSLClient::write
size_t write(uint8_t b) override
Definition: SSLClient.h:209
+
SSLClient::getClient
Client & getClient()
Returns a reference to the client object stored in this class. Take care not to break it.
Definition: SSLClient.h:358
+
SSLClient::removeSession
void removeSession(const char *host)
Clear the session corresponding to a host and IP.
Definition: SSLClient.cpp:264
+
SSLClient::getTimeout
unsigned int getTimeout() const
Get the timeout when waiting for an SSL response.
Definition: SSLClient.h:370
+
SSLClientParameters
This class stores data required for SSLClient to use mutual authentication.
Definition: SSLClientParameters.h:52
+
SSLClient::SSL_NONE
Definition: SSLClient.h:68
+
SSLClient::SSL_OK
Definition: SSLClient.h:45
+
SSLClient::SSL_INTERNAL_ERROR
Definition: SSLClient.h:55
diff --git a/docs/_s_s_l_client_parameters_8cpp.html b/docs/_s_s_l_client_parameters_8cpp.html new file mode 100644 index 0000000..7abe07a --- /dev/null +++ b/docs/_s_s_l_client_parameters_8cpp.html @@ -0,0 +1,114 @@ + + + + + + + +SSLClient: SSLClientParameters.cpp File Reference + + + + + + + + + + + + + + +
+
+ + + + + + +
+
SSLClient +  v1.5.0 +
+
+
+ + + + + + + +
+
+ +
+
+
+ +
+ +
+
+ + +
+ +
+ +
+
+Classes
+
+
SSLClientParameters.cpp File Reference
+
+
+
#include "SSLClientParameters.h"
+
+ + + +

+Classes

struct  ssl_pem_decode_state
 
+
+
+ + + + diff --git a/docs/_s_s_l_client_parameters_8cpp.js b/docs/_s_s_l_client_parameters_8cpp.js new file mode 100644 index 0000000..3671b5b --- /dev/null +++ b/docs/_s_s_l_client_parameters_8cpp.js @@ -0,0 +1,4 @@ +var _s_s_l_client_parameters_8cpp = +[ + [ "ssl_pem_decode_state", "structssl__pem__decode__state.html", "structssl__pem__decode__state" ] +]; \ No newline at end of file diff --git a/docs/_s_s_l_client_parameters_8h.html b/docs/_s_s_l_client_parameters_8h.html index 6c8b9fa..a9ad155 100644 --- a/docs/_s_s_l_client_parameters_8h.html +++ b/docs/_s_s_l_client_parameters_8h.html @@ -93,13 +93,14 @@ $(document).ready(function(){initNavTree('_s_s_l_client_parameters_8h.html','');
#include "bearssl.h"
+#include <vector>

Go to the source code of this file.

- - + +

Classes

struct  SSLClientParameters
 This struct stores data required for SSLClient to use mutual authentication. More...
class  SSLClientParameters
 This class stores data required for SSLClient to use mutual authentication. More...
 
diff --git a/docs/_s_s_l_client_parameters_8h_source.html b/docs/_s_s_l_client_parameters_8h_source.html index 0abb581..5656b99 100644 --- a/docs/_s_s_l_client_parameters_8h_source.html +++ b/docs/_s_s_l_client_parameters_8h_source.html @@ -90,10 +90,14 @@ $(document).ready(function(){initNavTree('_s_s_l_client_parameters_8h_source.htm
SSLClientParameters.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 
28 #include "bearssl.h"
29 
30 #ifndef SSLClientParameters_H_
31 #define SSLClientParameters_H_
32 
52 struct SSLClientParameters {
59  const br_x509_certificate* client_cert_chain;
61  const size_t chain_len;
63  const br_ec_private_key ec_key;
64 };
65 
66 #endif
SSLClientParameters::client_cert_chain
const br_x509_certificate * client_cert_chain
Pointer to the client certificate chain.
Definition: SSLClientParameters.h:59
-
SSLClientParameters
This struct stores data required for SSLClient to use mutual authentication.
Definition: SSLClientParameters.h:52
-
SSLClientParameters::chain_len
const size_t chain_len
Definition: SSLClientParameters.h:61
-
SSLClientParameters::ec_key
const br_ec_private_key ec_key
Definition: SSLClientParameters.h:63
+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 
28 #include "bearssl.h"
29 #undef min
30 #undef max
31 #include <vector>
32 
33 #ifndef SSLClientParameters_H_
34 #define SSLClientParameters_H_
35 
52 class SSLClientParameters {
53 public:
84  static SSLClientParameters fromPEM(const char* cert_pem, const size_t cert_len, const char* key_pem, const size_t key_len);
85 
112  static SSLClientParameters fromDER(const char* cert_der, const size_t cert_len, const char* key_der, const size_t key_len);
113 
115  const br_x509_certificate* getCertChain() const { return &m_cert_struct; }
116 
118  int getCertType() const { return br_skey_decoder_key_type(&m_key_struct); }
119 
121  const br_ec_private_key* getECKey() const { return br_skey_decoder_get_ec(&m_key_struct); }
122 
124  const br_rsa_private_key* getRSAKey() const { return br_skey_decoder_get_rsa(&m_key_struct); }
125 
126 protected:
127  SSLClientParameters(const char* cert, const size_t cert_len, const char* key, const size_t key_len, bool is_der);
128 
129 private:
130  const std::vector<char> m_cert;
131  const br_x509_certificate m_cert_struct;
132  const br_skey_decoder_context m_key_struct;
133 };
134 
135 #endif
SSLClientParameters::getCertType
int getCertType() const
Definition: SSLClientParameters.h:118
+
SSLClientParameters::fromDER
static SSLClientParameters fromDER(const char *cert_der, const size_t cert_len, const char *key_der, const size_t key_len)
Create mutual authentication parameters from a DER certificate and private key.
Definition: SSLClientParameters.cpp:92
+
SSLClientParameters::fromPEM
static SSLClientParameters fromPEM(const char *cert_pem, const size_t cert_len, const char *key_pem, const size_t key_len)
Create mutual authentication parameters from a PEM certificate and private key.
Definition: SSLClientParameters.cpp:87
+
SSLClientParameters::getRSAKey
const br_rsa_private_key * getRSAKey() const
Definition: SSLClientParameters.h:124
+
SSLClientParameters::SSLClientParameters
SSLClientParameters(const char *cert, const size_t cert_len, const char *key, const size_t key_len, bool is_der)
Definition: SSLClientParameters.cpp:81
+
SSLClientParameters::getCertChain
const br_x509_certificate * getCertChain() const
Definition: SSLClientParameters.h:115
+
SSLClientParameters
This class stores data required for SSLClient to use mutual authentication.
Definition: SSLClientParameters.h:52
+
SSLClientParameters::getECKey
const br_ec_private_key * getECKey() const
Definition: SSLClientParameters.h:121
diff --git a/docs/annotated.html b/docs/annotated.html index a1783da..24db1d6 100644 --- a/docs/annotated.html +++ b/docs/annotated.html @@ -94,7 +94,7 @@ $(document).ready(function(){initNavTree('annotated.html','');}); - +
 Cssl_pem_decode_state
 CSSLClientThe main SSLClient class. Check out README.md for more info
 CSSLClientParametersThis struct stores data required for SSLClient to use mutual authentication
 CSSLClientParametersThis class stores data required for SSLClient to use mutual authentication
 CSSLSessionThis class stores values which allow SSLClient to save and resume SSL sessions
diff --git a/docs/annotated_dup.js b/docs/annotated_dup.js index 997b666..a72472c 100644 --- a/docs/annotated_dup.js +++ b/docs/annotated_dup.js @@ -2,6 +2,6 @@ var annotated_dup = [ [ "ssl_pem_decode_state", "structssl__pem__decode__state.html", "structssl__pem__decode__state" ], [ "SSLClient", "class_s_s_l_client.html", "class_s_s_l_client" ], - [ "SSLClientParameters", "struct_s_s_l_client_parameters.html", "struct_s_s_l_client_parameters" ], + [ "SSLClientParameters", "class_s_s_l_client_parameters.html", "class_s_s_l_client_parameters" ], [ "SSLSession", "class_s_s_l_session.html", "class_s_s_l_session" ] ]; \ No newline at end of file diff --git a/docs/class_s_s_l_client-members.html b/docs/class_s_s_l_client-members.html index c43c371..b0ba8c6 100644 --- a/docs/class_s_s_l_client-members.html +++ b/docs/class_s_s_l_client-members.html @@ -109,7 +109,7 @@ $(document).ready(function(){initNavTree('class_s_s_l_client.html','');}); read(uint8_t *buf, size_t size) overrideSSLClient read() overrideSSLClientinline removeSession(const char *host)SSLClient - setMutualAuthParams(const SSLClientParameters *params)SSLClient + setMutualAuthParams(const SSLClientParameters &params)SSLClient setTimeout(unsigned int t)SSLClientinline SSL_BR_CONNECT_FAIL enum valueSSLClient SSL_BR_WRITE_ERROR enum valueSSLClient diff --git a/docs/class_s_s_l_client.html b/docs/class_s_s_l_client.html index a22ac7e..66de223 100644 --- a/docs/class_s_s_l_client.html +++ b/docs/class_s_s_l_client.html @@ -166,9 +166,9 @@ Public Member Functions 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...
-  +void setMutualAuthParams (const SSLClientParameters &params) + Add a client certificate and enable support for mutual auth. More...
+  SSLSession * getSession (const char *host)  Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist. More...
  @@ -810,8 +810,8 @@ There must be a trust anchor given to the constructor that corresponds to the ce - -

◆ setMutualAuthParams()

+ +

◆ setMutualAuthParams()

@@ -819,7 +819,7 @@ There must be a trust anchor given to the constructor that corresponds to the ce void SSLClient::setMutualAuthParams ( - const SSLClientParameters *  + const SSLClientParameters &  params) diff --git a/docs/class_s_s_l_client.js b/docs/class_s_s_l_client.js index d2eadc2..861496f 100644 --- a/docs/class_s_s_l_client.js +++ b/docs/class_s_s_l_client.js @@ -30,7 +30,7 @@ var class_s_s_l_client = [ "read", "class_s_s_l_client.html#a4c5420541a06213133ae308a3bca1c95", null ], [ "read", "class_s_s_l_client.html#aef1b52f4ad9633126cb68739175920eb", null ], [ "removeSession", "class_s_s_l_client.html#ad5d9d8a4187a3f8918bf66af83e733c4", null ], - [ "setMutualAuthParams", "class_s_s_l_client.html#a9e7ce7f8a72d7cdc071be3fa7a4c8f29", null ], + [ "setMutualAuthParams", "class_s_s_l_client.html#aeee217b5558dfb0724f2319888a77256", null ], [ "setTimeout", "class_s_s_l_client.html#a8da354f30537c1064d554921937a73ae", null ], [ "stop", "class_s_s_l_client.html#ad8ed697371748e31e01c3f697bc36cbe", null ], [ "write", "class_s_s_l_client.html#a03c7926938acd57cfc3b982edf725a86", null ], diff --git a/docs/class_s_s_l_client_parameters-members.html b/docs/class_s_s_l_client_parameters-members.html new file mode 100644 index 0000000..caa4047 --- /dev/null +++ b/docs/class_s_s_l_client_parameters-members.html @@ -0,0 +1,114 @@ + + + + + + + +SSLClient: Member List + + + + + + + + + + + + + + +
+
+ + + + + + +
+
SSLClient +  v1.5.0 +
+
+
+ + + + + + + +
+
+ +
+
+
+ +
+ +
+
+ + +
+ +
+ +
+
+
SSLClientParameters Member List
+
+
+ +

This is the complete list of members for SSLClientParameters, including all inherited members.

+ + + + + + + + +
fromDER(const char *cert_der, const size_t cert_len, const char *key_der, const size_t key_len)SSLClientParametersstatic
fromPEM(const char *cert_pem, const size_t cert_len, const char *key_pem, const size_t key_len)SSLClientParametersstatic
getCertChain() constSSLClientParametersinline
getCertType() constSSLClientParametersinline
getECKey() constSSLClientParametersinline
getRSAKey() constSSLClientParametersinline
SSLClientParameters(const char *cert, const size_t cert_len, const char *key, const size_t key_len, bool is_der)SSLClientParametersprotected
+
+ + + + diff --git a/docs/class_s_s_l_client_parameters.html b/docs/class_s_s_l_client_parameters.html new file mode 100644 index 0000000..9811c6e --- /dev/null +++ b/docs/class_s_s_l_client_parameters.html @@ -0,0 +1,436 @@ + + + + + + + +SSLClient: SSLClientParameters Class Reference + + + + + + + + + + + + + + +
+
+ + + + + + +
+
SSLClient +  v1.5.0 +
+
+
+ + + + + + + +
+
+ +
+
+
+ +
+ +
+
+ + +
+ +
+ +
+
+Public Member Functions | +Static Public Member Functions | +Protected Member Functions | +List of all members
+
+
SSLClientParameters Class Reference
+
+
+ +

This class stores data required for SSLClient to use mutual authentication. + More...

+ +

#include <SSLClientParameters.h>

+ + + + + + + + + + +

+Public Member Functions

const br_x509_certificate * getCertChain () const
 
int getCertType () const
 
const br_ec_private_key * getECKey () const
 
const br_rsa_private_key * getRSAKey () const
 
+ + + + + + + +

+Static Public Member Functions

static SSLClientParameters fromPEM (const char *cert_pem, const size_t cert_len, const char *key_pem, const size_t key_len)
 Create mutual authentication parameters from a PEM certificate and private key. More...
 
static SSLClientParameters fromDER (const char *cert_der, const size_t cert_len, const char *key_der, const size_t key_len)
 Create mutual authentication parameters from a DER certificate and private key. More...
 
+ + + +

+Protected Member Functions

 SSLClientParameters (const char *cert, const size_t cert_len, const char *key, const size_t key_len, bool is_der)
 
+

Detailed Description

+

This class stores data required for SSLClient to use mutual authentication.

+

SSLClientParameters.h

+

This file contains a simple utility class to store parameters about an SSL Session for reuse later.TLS mutual authentication is a process in which both the server and client perform cryptographic operations to verify the authenticity of eachother, for more information check out this article: https://medium.com/sitewards/the-magic-of-tls-x509-and-mutual-authentication-explained-b2162dec4401 . If this struct is provided to SSLClient::SSLClient via SSLClient::setMutualAuthParams, SSLClient will automatically send a client certificate if one is requested by the server. This will happen for all SSLClient connections, and may cause issues for websites that do not need mutual authentication—as a result, please only turn on mutual authentication if you are sure it is neccesary.

+

SSLClientParameters supports both ECC and RSA client certificates. I recommend using ECC certificates if possible, as SSLClientParameters will make a copy of both the certificate and the private key in memory, and ECC keys tend to be smaller than RSA ones.

+

Constructor & Destructor Documentation

+ +

◆ SSLClientParameters()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SSLClientParameters::SSLClientParameters (const char * cert,
const size_t cert_len,
const char * key,
const size_t key_len,
bool is_der 
)
+ 		+protected
+
+ +
+
+

Member Function Documentation

+ +

◆ fromDER()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SSLClientParameters SSLClientParameters::fromDER (const char * cert_der,
const size_t cert_len,
const char * key_der,
const size_t key_len 
)
+ 		+static
+
+ +

Create mutual authentication parameters from a DER certificate and private key.

+

Use this function to create a mutual tls context from a DER client certificate and DER private key. This function will copy the certificate and private key, extract the needed information from the private key, and store both that information and the copied cert into a SSLClientParameters object. Given the key parsed correctly, you can then use SSLClient::setMutualAuthParams at the begining of your sketch to enable mTLS with SSLClient. This function supports both ECC and RSA certificate/private keys (use EC keys wherever possible, as they are signifigantly smaller and faster), however SSLClient only supports the p256, p384, and p512 curves for ECC.

+

Because SSLClientParameters creates a copy of both the certificate and key, you do not need to ensure that the data pointed to by cert_der or key_der is accessible after this function (i.e. you can free them afterwards).

+

Please note that if the private key is incorrect, this function will not report an error, and instead SSLClient will fall back to regular TLS when making a connection.

+
Parameters
+ + + + + +
cert_derA DER encoded certificate, can be ECC or RSA.
cert_lenThe number of bytes in cert_der.
key_derA DER encoded private key, can be ECC or RSA.
key_lenThe number of bytes in key_ders
+
+
+
Returns
An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
+ +
+
+ +

◆ fromPEM()

+ +
+
+ + + + + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
SSLClientParameters SSLClientParameters::fromPEM (const char * cert_pem,
const size_t cert_len,
const char * key_pem,
const size_t key_len 
)
+ 		+static
+
+ +

Create mutual authentication parameters from a PEM certificate and private key.

+

Use this function to create a mutual tls context from a PEM client certificate and PEM private key. This function will convert the PEM certificates into DER format (creating a copy in the process), extract the needed information from the private key, and store that information into a SSLClientParameters object. Given the certifiate and key parsed correctly, you can then use SSLClient::setMutualAuthParams at the begining of your sketch to enable mTLS with SSLClient. This function supports both ECC and RSA certificate/private keys (use EC keys wherever possible, as they are signifigantly smaller and faster), however SSLClient only supports the p256, p384, and p512 curves for ECC.

+

Because SSLClientParameters creates a copy of both the certificate and key, you do not need to ensure that the data pointed to by cert_pem or key_pem is accessible after this function (i.e. you can free them afterwards).

+

Please note that if the certificate or private key are incorrect, this function will not report an error, and instead SSLClient will fall back to regular TLS when making a connection.

+
Parameters
+ + + + + +
cert_pemA PEM formatted certificate, including the "BEGIN" and "END" header/footers. Can be ECC or RSA. cert_pem supports both LF and CRLF for endlines, but all other constraints on a valid PEM file apply.
cert_lenThe number of bytes in cert_pem.
key_pemA PEM formatted private key, including the "BEGIN" and "END" header/footers. Can be ECC or RSA. key_pem supports both LF and CRLF for endlines, but all other constraints \ on a valid PEM file apply.
key_lenThe number of bytes in key_pem
+
+
+
Returns
An SSLClientParameters context, to be used with SSLClient::setMutualAuthParams.
+ +
+
+ +

◆ getCertChain()

+ +
+
+ + + + + +
+ + + + + + + +
const br_x509_certificate* SSLClientParameters::getCertChain () const
+ 		+inline
+
+

mTLS information used by SSLClient during authentication

+ +
+
+ +

◆ getCertType()

+ +
+
+ + + + + +
+ + + + + + + +
int SSLClientParameters::getCertType () const
+ 		+inline
+
+

mTLS information used by SSLClient during authentication

+ +
+
+ +

◆ getECKey()

+ +
+
+ + + + + +
+ + + + + + + +
const br_ec_private_key* SSLClientParameters::getECKey () const
+ 		+inline
+
+

mTLS information used by SSLClient during authentication

+ +
+
+ +

◆ getRSAKey()

+ +
+
+ + + + + +
+ + + + + + + +
const br_rsa_private_key* SSLClientParameters::getRSAKey () const
+ 		+inline
+
+

mTLS information used by SSLClient during authentication

+ +
+
+
The documentation for this class was generated from the following files: +
+
+ + + + diff --git a/docs/class_s_s_l_client_parameters.js b/docs/class_s_s_l_client_parameters.js new file mode 100644 index 0000000..11f9ac1 --- /dev/null +++ b/docs/class_s_s_l_client_parameters.js @@ -0,0 +1,8 @@ +var class_s_s_l_client_parameters = +[ + [ "SSLClientParameters", "class_s_s_l_client_parameters.html#a97213b5554e90908fbf284669b5f22f3", null ], + [ "getCertChain", "class_s_s_l_client_parameters.html#af5686b2c601812f55477a7089b3b2c2d", null ], + [ "getCertType", "class_s_s_l_client_parameters.html#a90d581703308881714d64d1ada785ad2", null ], + [ "getECKey", "class_s_s_l_client_parameters.html#ad9beb80ce98ed9aa34db28783f0264c5", null ], + [ "getRSAKey", "class_s_s_l_client_parameters.html#a82c21b0ae4690a6b7842a0d74b12f67f", null ] +]; \ No newline at end of file diff --git a/docs/classes.html b/docs/classes.html index 31016db..c746b99 100644 --- a/docs/classes.html +++ b/docs/classes.html @@ -94,7 +94,7 @@ $(document).ready(function(){initNavTree('classes.html','');}); - +
  s  
SSLClient   SSLSession   
SSLClientParameters   
SSLClientParameters   
ssl_pem_decode_state   
diff --git a/docs/dir_732ec7fb04c2890977d3e4bc2bf648f7.html b/docs/dir_732ec7fb04c2890977d3e4bc2bf648f7.html index b5a4cd0..55fc22c 100644 --- a/docs/dir_732ec7fb04c2890977d3e4bc2bf648f7.html +++ b/docs/dir_732ec7fb04c2890977d3e4bc2bf648f7.html @@ -97,12 +97,10 @@ Files   file  SSLClient.h [code]   +file  SSLClientParameters.cpp +  file  SSLClientParameters.h [code]   -file  SSLObj.cpp -  -file  SSLObj.h [code] -  file  SSLSession.h [code]   file  time_macros.h [code] diff --git a/docs/files.html b/docs/files.html index 7c976e6..ff8604b 100644 --- a/docs/files.html +++ b/docs/files.html @@ -94,11 +94,10 @@ $(document).ready(function(){initNavTree('files.html','');}); - - - - - + + + +
 SSLClient.cpp
 SSLClient.h
 SSLClientParameters.h
 SSLObj.cpp
 SSLObj.h
 SSLSession.h
 time_macros.h
 SSLClientParameters.cpp
 SSLClientParameters.h
 SSLSession.h
 time_macros.h
diff --git a/docs/files_dup.js b/docs/files_dup.js index 8050b9b..be727b1 100644 --- a/docs/files_dup.js +++ b/docs/files_dup.js @@ -4,11 +4,10 @@ var files_dup = [ "SSLClient.h", "_s_s_l_client_8h.html", [ [ "SSLClient", "class_s_s_l_client.html", "class_s_s_l_client" ] ] ], + [ "SSLClientParameters.cpp", "_s_s_l_client_parameters_8cpp.html", "_s_s_l_client_parameters_8cpp" ], [ "SSLClientParameters.h", "_s_s_l_client_parameters_8h.html", [ - [ "SSLClientParameters", "struct_s_s_l_client_parameters.html", "struct_s_s_l_client_parameters" ] + [ "SSLClientParameters", "class_s_s_l_client_parameters.html", "class_s_s_l_client_parameters" ] ] ], - [ "SSLObj.cpp", "_s_s_l_obj_8cpp.html", "_s_s_l_obj_8cpp" ], - [ "SSLObj.h", "_s_s_l_obj_8h.html", "_s_s_l_obj_8h" ], [ "SSLSession.h", "_s_s_l_session_8h.html", [ [ "SSLSession", "class_s_s_l_session.html", "class_s_s_l_session" ] ] ], diff --git a/docs/functions.html b/docs/functions.html index 7359072..9ec5b7f 100644 --- a/docs/functions.html +++ b/docs/functions.html @@ -96,12 +96,6 @@ $(document).ready(function(){initNavTree('functions.html','');});

- c -