lmoskala/SSLClient
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

regenerated documentation

Browse source
This commit is contained in:
Noah Laptop 2019-03-31 16:42:28 -07:00
parent 5c643d015e
commit 431df02b5b
23 changed files with 416 additions and 147 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

23
README.md
View file

@ -51,7 +51,7 @@ For more information on SSLClient, check out the [examples](./examples), [API do
SSLClient was created to integrate SSL seamlessly with the Arduino infrastructure, and so it does just that: implementing the brilliant [BearSSL](https://bearssl.org/) as a proxy in front of any Arduino socket library. BearSSL is designed with low flash footprint in mind, and as a result does little verification of improper programming, relying on the developer to ensure the code is correct. Since SSLClient is built specifically for the Arduino ecosystem, most of the code adds those programming checks back in, making debugging a fast and simple process. The rest manages the state of BearSSL, and ensures a manageable memory footprint. SSLClient was created to integrate SSL seamlessly with the Arduino infrastructure, and so it does just that: implementing the brilliant [BearSSL](https://bearssl.org/) as a proxy in front of any Arduino socket library. BearSSL is designed with low flash footprint in mind, and as a result does little verification of improper programming, relying on the developer to ensure the code is correct. Since SSLClient is built specifically for the Arduino ecosystem, most of the code adds those programming checks back in, making debugging a fast and simple process. The rest manages the state of BearSSL, and ensures a manageable memory footprint.
Additionally, the bulk of SSLClient is split into two components: a template class [SSLClient](./src/SSLClient.h), and an implementation class [SSLClientImpl](./src/SSLClientImpl.h). The template class serves to abstract some functions not implemented in the Arduino Client interface (such as `EthernetClient::remoteIP`), and the implementation class is the rest of the SSLClient library. Additionally, the bulk of SSLClient is split into two components: a template class [SSLClient](./src/SSLClient.h), and an implementation class [SSLClientImpl](./src/SSLClientImpl.h). The template class serves to abstract some functions not implemented in the Arduino Client interface (such as EthernetClient::remoteIP), and the implementation class is the rest of the SSLClient library.
## Other Features ## Other Features
@ -60,13 +60,13 @@ SSLClient also allows for changing the debugging level by adding an additional p
```C++ ```C++
SSLClient<EthernetClient> client(EthernetClient(), TAs, (size_t)2, A7, SSL_INFO); SSLClient<EthernetClient> client(EthernetClient(), TAs, (size_t)2, A7, SSL_INFO);
``` ```
Logging is always outputted through the [Arduino Serial interface](https://www.arduino.cc/reference/en/language/functions/communication/serial/), so you'll need to setup Serial before you can view the SSL logs. Log levels are enumerated in [Error](./src/SSLClientImpl.h). The log level is set to `SSL_WARN` by default. Logging is always outputted through the [Arduino Serial interface](https://www.arduino.cc/reference/en/language/functions/communication/serial/), so you'll need to setup Serial before you can view the SSL logs. Log levels are enumerated in ::DebugLevel. The log level is set to `SSL_WARN` by default.
### Errors ### Errors
When SSLClient encounters an error, it will attempt to terminate the SSL session gracefully if possible, and then close the socket. Simple error information can be found from `SSLClient::getWriteError()`, which will return a value from [this enumeration](link-me). For more detailed diagnostics, you can look at the serial logs, which will be displayed if the log level is at `SSL_ERROR` or lower. When SSLClient encounters an error, it will attempt to terminate the SSL session gracefully if possible, and then close the socket. Simple error information can be found from SSLClient::getWriteError(), which will return a value from the ::Error enum. For more detailed diagnostics, you can look at the serial logs, which will be displayed if the log level is at `SSL_ERROR` or lower.
### Write Buffering ### Write Buffering
As you may have noticed in the documentation for [SSLClient::write](link-me), calling this function does not actually write to the network. Instead, you must call [SSLClient::available](link-me) or [SSLClient::flush](link-me), which will detect that the buffer is ready and write to the network (see [SSLClient::write](link-me) for details). As you may have noticed in the documentation for SSLClient::write, calling this function does not actually write to the network. Instead, you must call SSLClient::available or SSLClient::flush, which will detect that the buffer is ready and write to the network (see SSLClient::write for details).
This was implemented as a buffered function because examples in Arduino libraries will often write to the network like so: This was implemented as a buffered function because examples in Arduino libraries will often write to the network like so:
```C++ ```C++
@ -114,12 +114,23 @@ SSLClient automatically stores an IP address and hostname in each session, ensur
You can test whether or not a website can resume SSL Sessions using the [Session Example](./examples/Session_Example/Session_Example.ino) included with this library. Because of all the confounding factors of SSL Sessions, it is generally prudent while programming to assume the session will always fail to resume. You can test whether or not a website can resume SSL Sessions using the [Session Example](./examples/Session_Example/Session_Example.ino) included with this library. Because of all the confounding factors of SSL Sessions, it is generally prudent while programming to assume the session will always fail to resume.
SSL sessions take a lot of memory to store, so by default SSLClient will only store one at a time. You can change this behavior by adding the following to your SSLClient declaration:
```C++
SSLClient<EthernetClient, SomeNumber> client(EthernetClient(), TAs, 2, A7);
```
Where `SomeNumber` is the number of sessions you would like to store. For example this declaration can store 3 sessions:
```C++
SSLClient<EthernetClient, 3> client(EthernetClient(), TAs, 2, A7);
```
Sessions are managed internally using the SSLSession::getSession function. This function will cycle through sessions in a rotating order, allowing the session cache to continually overwrite old sessions. In general, it is a good idea to use a SessionCache size equal to the number of domains you plan on connecting to.
If you need to clear a session, you can do so using the SSLSession::removeSession function.
## Implementation Gotchas ## Implementation Gotchas
Some ideas that didn't quite fit in the API documentation. Some ideas that didn't quite fit in the API documentation.
### Certificate Verification ### Certificate Verification
SSLClient uses BearSSL's [minimal x509 verification engine](https://bearssl.org/x509.html#the-minimal-engine) to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. Check out [this document](./TrustAnchors.md) for more details on this component of SSLClient. SSLClient uses BearSSL's [minimal x509 verification engine](https://bearssl.org/x509.html#the-minimal-engine) to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. Check out [this document](./TrustAnchors.md) for more details on this component of SSLClient.
BearSSL also features a [known certificate validation engine](https://bearssl.org/x509.html#the-known-key-engine), which only allows for a single domain in exchange for a significantly reduced resource usage (flash and CPU time). This functionality is planned to be implemented in the future. BearSSL also features a [known certificate validation engine](https://bearssl.org/x509.html#the-known-key-engine), which only allows for a single domain in exchange for a significantly reduced resource usage (flash and CPU time). This functionality is planned to be implemented in the future.
@ -141,7 +152,7 @@ In order to remedy this problem, the device must be able to read the data faster
* If none of the above are viable, it is possible to implement your own Client class which has an internal buffer much larger than both the driver and BearSSL. This would require in-depth knowledge of programming and the communication shield you are working with, as well as a microcontroller with a significant amount of RAM. * If none of the above are viable, it is possible to implement your own Client class which has an internal buffer much larger than both the driver and BearSSL. This would require in-depth knowledge of programming and the communication shield you are working with, as well as a microcontroller with a significant amount of RAM.
### Cipher Support ### Cipher Support
By default, SSLClient supports only TLS1.2 and the ciphers listed in [this file](./src/TLS12_only_profile) under `suites[]`, and the list is relatively small to keep the connection secure and the flash footprint down. These ciphers should work for most applications, however if for some reason you would like to use an older version of TLS or a different cipher, you can change the BearSSL profile being used by SSLClient to an [alternate one with support for older protocols](./src/bearssl/src/ssl). To do this, edit `SSLClientImpl::SSLClientImpl` to change these lines: By default, SSLClient supports only TLS1.2 and the ciphers listed in [this file](./src/TLS12_only_profile.c) under `suites[]`, and the list is relatively small to keep the connection secure and the flash footprint down. These ciphers should work for most applications, however if for some reason you would like to use an older version of TLS or a different cipher, you can change the BearSSL profile being used by SSLClient to an [alternate one with support for older protocols](./src/bearssl/src/ssl). To do this, edit `SSLClientImpl::SSLClientImpl` to change these lines:
```C++ ```C++
br_client_init_TLS12_only(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num); br_client_init_TLS12_only(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num);
// comment the above line and uncomment the line below if you're having trouble connecting over SSL // comment the above line and uncomment the line below if you're having trouble connecting over SSL

2
docs/html/_s_s_l_client_8h.html
View file

@ -104,7 +104,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_8h.html','');});
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr> Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html">SSLClient&lt; C, SessionCache &gt;</a></td></tr> <tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html">SSLClient&lt; C, SessionCache &gt;</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> class Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info. <a href="class_s_s_l_client.html#details">More...</a><br /></td></tr> <tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> class. Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info. <a href="class_s_s_l_client.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls"> </table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="define-members"></a>

44
docs/html/_s_s_l_client_8h_source.html
View file

File diff suppressed because one or more lines are too long

14
docs/html/_s_s_l_client_impl_8h.html
View file

@ -104,7 +104,7 @@ $(document).ready(function(){initNavTree('_s_s_l_client_impl_8h.html','');});
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr> Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client_impl.html">SSLClientImpl</a></td></tr> <tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client_impl.html">SSLClientImpl</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. <a href="class_s_s_l_client_impl.html#details">More...</a><br /></td></tr> <tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>. <a href="class_s_s_l_client_impl.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table><table class="memberdecls"> </table><table class="memberdecls">
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="enum-members"></a>
@ -127,7 +127,7 @@ Enumerations</h2></td></tr>
<a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d">SSL_WARN</a> = 2, <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d">SSL_WARN</a> = 2,
<a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a8c0bb62be3d0e6bfe5ed2f7ebbed3d91">SSL_INFO</a> = 3 <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a8c0bb62be3d0e6bfe5ed2f7ebbed3d91">SSL_INFO</a> = 3
}</td></tr> }</td></tr>
<tr class="memdesc:ab658e6d84759440dbf3c890446075395"><td class="mdescLeft">&#160;</td><td class="mdescRight">Level of verbosity used in logging for <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. <a href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">More...</a><br /></td></tr> <tr class="memdesc:ab658e6d84759440dbf3c890446075395"><td class="mdescLeft">&#160;</td><td class="mdescRight">Level of verbosity used in logging for <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>. <a href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">More...</a><br /></td></tr>
<tr class="separator:ab658e6d84759440dbf3c890446075395"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ab658e6d84759440dbf3c890446075395"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table> </table>
<h2 class="groupheader">Enumeration Type Documentation</h2> <h2 class="groupheader">Enumeration Type Documentation</h2>
@ -143,8 +143,8 @@ Enumerations</h2></td></tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Level of verbosity used in logging for <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. </p> <p>Level of verbosity used in logging for <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>. </p>
<p>Use these values when initializing <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to set how many logs you would like to see in the Serial monitor. </p> <p>Use these values when initializing <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to set how many logs you would like to see in the Serial monitor. </p>
<table class="fieldtable"> <table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ab658e6d84759440dbf3c890446075395af16e73d8cce9a2c987bde5afe5524d7f"></a>SSL_NONE&#160;</td><td class="fielddoc"><p>No logging output </p> <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="ab658e6d84759440dbf3c890446075395af16e73d8cce9a2c987bde5afe5524d7f"></a>SSL_NONE&#160;</td><td class="fielddoc"><p>No logging output </p>
</td></tr> </td></tr>
@ -171,7 +171,7 @@ Enumerations</h2></td></tr>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Static constants defining the possible errors encountered. </p> <p>Static constants defining the possible errors encountered. </p>
<p>If <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> encounters an error, it will generally output logs into the serial monitor. If you need a way of programmatically checking the errors, you can do so with SSLClient::getWriteError(), which will return one of these values. </p> <p>If <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> encounters an error, it will generally output logs into the serial monitor. If you need a way of programmatically checking the errors, you can do so with SSLClient::getWriteError(), which will return one of these values. </p>
<table class="fieldtable"> <table class="fieldtable">
<tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5a1218c16a5bf50589e0c498983851612c"></a>SSL_OK&#160;</td><td class="fielddoc"></td></tr> <tr><th colspan="2">Enumerator</th></tr><tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5a1218c16a5bf50589e0c498983851612c"></a>SSL_OK&#160;</td><td class="fielddoc"></td></tr>
<tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5aaa79045423a355885738cd239dff6c2b"></a>SSL_CLIENT_CONNECT_FAIL&#160;</td><td class="fielddoc"><p>The underlying client failed to connect, probably not an issue with SSL </p> <tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5aaa79045423a355885738cd239dff6c2b"></a>SSL_CLIENT_CONNECT_FAIL&#160;</td><td class="fielddoc"><p>The underlying client failed to connect, probably not an issue with SSL </p>
@ -182,9 +182,9 @@ Enumerations</h2></td></tr>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5a1d9afd51e0012e791f099657797c9aa9"></a>SSL_BR_WRITE_ERROR&#160;</td><td class="fielddoc"><p>An internal error occurred with BearSSL, check logs for diagnosis. </p> <tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5a1d9afd51e0012e791f099657797c9aa9"></a>SSL_BR_WRITE_ERROR&#160;</td><td class="fielddoc"><p>An internal error occurred with BearSSL, check logs for diagnosis. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5afd588a56dcccf4f6943defa7ab699afc"></a>SSL_INTERNAL_ERROR&#160;</td><td class="fielddoc"><p>An internal error occurred with <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>, and you probably need to submit an issue on Github. </p> <tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5afd588a56dcccf4f6943defa7ab699afc"></a>SSL_INTERNAL_ERROR&#160;</td><td class="fielddoc"><p>An internal error occurred with <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>, and you probably need to submit an issue on Github. </p>
</td></tr> </td></tr>
<tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5adec799caf92b4fe2b6d2b362136f6ef6"></a>SSL_OUT_OF_MEMORY&#160;</td><td class="fielddoc"><p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> detected that there was not enough memory (&gt;8000 bytes) to continue. </p> <tr><td class="fieldname"><a id="a2c3e4bb40f36b262a5214e2da2bca9c5adec799caf92b4fe2b6d2b362136f6ef6"></a>SSL_OUT_OF_MEMORY&#160;</td><td class="fielddoc"><p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> detected that there was not enough memory (&gt;8000 bytes) to continue. </p>
</td></tr> </td></tr>
</table> </table>

2
docs/html/_s_s_l_session_8h.html
View file

@ -102,7 +102,7 @@ $(document).ready(function(){initNavTree('_s_s_l_session_8h.html','');});
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="nested-classes"></a>
Classes</h2></td></tr> Classes</h2></td></tr>
<tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html">SSLSession</a></td></tr> <tr class="memitem:"><td class="memItemLeft" align="right" valign="top">class &#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html">SSLSession</a></td></tr>
<tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions. <a href="class_s_s_l_session.html#details">More...</a><br /></td></tr> <tr class="memdesc:"><td class="mdescLeft">&#160;</td><td class="mdescRight">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions. <a href="class_s_s_l_session.html#details">More...</a><br /></td></tr>
<tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table> </table>
</div><!-- contents --> </div><!-- contents -->

6
docs/html/_s_s_l_session_8h_source.html
View file

File diff suppressed because one or more lines are too long

6
docs/html/annotated.html
View file

@ -93,9 +93,9 @@ $(document).ready(function(){initNavTree('annotated.html','');});
<div class="contents"> <div class="contents">
<div class="textblock">Here are the classes, structs, unions and interfaces with brief descriptions:</div><div class="directory"> <div class="textblock">Here are the classes, structs, unions and interfaces with brief descriptions:</div><div class="directory">
<table class="directory"> <table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client.html" target="_self">SSLClient</a></td><td class="desc">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> class Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info </td></tr> <tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client.html" target="_self">SSLClient</a></td><td class="desc">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> class. Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info </td></tr>
<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client_impl.html" target="_self">SSLClientImpl</a></td><td class="desc">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> </td></tr> <tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client_impl.html" target="_self">SSLClientImpl</a></td><td class="desc">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> </td></tr>
<tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_session.html" target="_self">SSLSession</a></td><td class="desc">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions </td></tr> <tr id="row_2_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_session.html" target="_self">SSLSession</a></td><td class="desc">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions </td></tr>
</table> </table>
</div><!-- directory --> </div><!-- directory -->
</div><!-- contents --> </div><!-- contents -->

101
docs/html/class_s_s_l_client.html
View file

@ -96,7 +96,7 @@ $(document).ready(function(){initNavTree('class_s_s_l_client.html','');});
</div><!--header--> </div><!--header-->
<div class="contents"> <div class="contents">
<p>The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> class Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info. <p>The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> class. Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info.
<a href="class_s_s_l_client.html#details">More...</a></p> <a href="class_s_s_l_client.html#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="_s_s_l_client_8h_source.html">SSLClient.h</a>&gt;</code></p> <p><code>#include &lt;<a class="el" href="_s_s_l_client_8h_source.html">SSLClient.h</a>&gt;</code></p>
@ -113,7 +113,7 @@ Inheritance diagram for SSLClient&lt; C, SessionCache &gt;:</div>
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pub-methods"></a>
Public Member Functions</h2></td></tr> Public Member Functions</h2></td></tr>
<tr class="memitem:ae9a7509bc8a18f67e286547c19deb3c0"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0">SSLClient</a> (const C &amp;client, const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">DebugLevel</a> debug=<a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d">SSL_WARN</a>)</td></tr> <tr class="memitem:ae9a7509bc8a18f67e286547c19deb3c0"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0">SSLClient</a> (const C &amp;client, const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">DebugLevel</a> debug=<a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d">SSL_WARN</a>)</td></tr>
<tr class="memdesc:ae9a7509bc8a18f67e286547c19deb3c0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialize <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> with all of the prerequisites needed. <a href="#ae9a7509bc8a18f67e286547c19deb3c0">More...</a><br /></td></tr> <tr class="memdesc:ae9a7509bc8a18f67e286547c19deb3c0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Initialize <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> with all of the prerequisites needed. <a href="#ae9a7509bc8a18f67e286547c19deb3c0">More...</a><br /></td></tr>
<tr class="separator:ae9a7509bc8a18f67e286547c19deb3c0"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ae9a7509bc8a18f67e286547c19deb3c0"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae6540b9a02f1392bf2ac48421189f70e"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae6540b9a02f1392bf2ac48421189f70e">connect</a> (IPAddress ip, uint16_t port)</td></tr> <tr class="memitem:ae6540b9a02f1392bf2ac48421189f70e"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae6540b9a02f1392bf2ac48421189f70e">connect</a> (IPAddress ip, uint16_t port)</td></tr>
<tr class="memdesc:ae6540b9a02f1392bf2ac48421189f70e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Connect over SSL to a host specified by an IP address. <a href="#ae6540b9a02f1392bf2ac48421189f70e">More...</a><br /></td></tr> <tr class="memdesc:ae6540b9a02f1392bf2ac48421189f70e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Connect over SSL to a host specified by an IP address. <a href="#ae6540b9a02f1392bf2ac48421189f70e">More...</a><br /></td></tr>
@ -127,28 +127,28 @@ Public Member Functions</h2></td></tr>
<tr class="memdesc:a3a48b190985cdea2eba79ef0bdc80461"><td class="mdescLeft">&#160;</td><td class="mdescRight">Write some bytes to the SSL connection. <a href="#a3a48b190985cdea2eba79ef0bdc80461">More...</a><br /></td></tr> <tr class="memdesc:a3a48b190985cdea2eba79ef0bdc80461"><td class="mdescLeft">&#160;</td><td class="mdescRight">Write some bytes to the SSL connection. <a href="#a3a48b190985cdea2eba79ef0bdc80461">More...</a><br /></td></tr>
<tr class="separator:a3a48b190985cdea2eba79ef0bdc80461"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a3a48b190985cdea2eba79ef0bdc80461"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a40ec85568d0aec376219125b604dbc29"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29">available</a> ()</td></tr> <tr class="memitem:a40ec85568d0aec376219125b604dbc29"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29">available</a> ()</td></tr>
<tr class="memdesc:a40ec85568d0aec376219125b604dbc29"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the number of bytes availible to read from the SSL Socket. <a href="#a40ec85568d0aec376219125b604dbc29">More...</a><br /></td></tr> <tr class="memdesc:a40ec85568d0aec376219125b604dbc29"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the number of bytes available to read from the data that has been received and decrypted. <a href="#a40ec85568d0aec376219125b604dbc29">More...</a><br /></td></tr>
<tr class="separator:a40ec85568d0aec376219125b604dbc29"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a40ec85568d0aec376219125b604dbc29"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac70b900ff798f9fd33f6367fcc9fad77"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ac70b900ff798f9fd33f6367fcc9fad77">read</a> ()</td></tr> <tr class="memitem:ac70b900ff798f9fd33f6367fcc9fad77"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ac70b900ff798f9fd33f6367fcc9fad77">read</a> ()</td></tr>
<tr class="memdesc:ac70b900ff798f9fd33f6367fcc9fad77"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read a single byte, or -1 if none is available. <a href="#ac70b900ff798f9fd33f6367fcc9fad77">More...</a><br /></td></tr> <tr class="memdesc:ac70b900ff798f9fd33f6367fcc9fad77"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read a single byte, or -1 if none is available. <a href="#ac70b900ff798f9fd33f6367fcc9fad77">More...</a><br /></td></tr>
<tr class="separator:ac70b900ff798f9fd33f6367fcc9fad77"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ac70b900ff798f9fd33f6367fcc9fad77"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf">read</a> (uint8_t *buf, size_t size)</td></tr> <tr class="memitem:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf">read</a> (uint8_t *buf, size_t size)</td></tr>
<tr class="memdesc:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read size bytes from the SSL socket buffer, copying them into *buf, and return the number of bytes read. <a href="#ae31dd88a1af8ec3794fb48f26a3dd4bf">More...</a><br /></td></tr> <tr class="memdesc:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="mdescLeft">&#160;</td><td class="mdescRight">Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes read. <a href="#ae31dd88a1af8ec3794fb48f26a3dd4bf">More...</a><br /></td></tr>
<tr class="separator:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ae31dd88a1af8ec3794fb48f26a3dd4bf"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a227b1cbbe91bcb21153c09f97d0dd484"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a227b1cbbe91bcb21153c09f97d0dd484">peek</a> ()</td></tr> <tr class="memitem:a227b1cbbe91bcb21153c09f97d0dd484"><td class="memItemLeft" align="right" valign="top">virtual int&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a227b1cbbe91bcb21153c09f97d0dd484">peek</a> ()</td></tr>
<tr class="memdesc:a227b1cbbe91bcb21153c09f97d0dd484"><td class="mdescLeft">&#160;</td><td class="mdescRight">view the first byte of the buffer, without removing it from the <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> Buffer The implementation for this function can be found in SSLClientImpl::peek <a href="#a227b1cbbe91bcb21153c09f97d0dd484">More...</a><br /></td></tr> <tr class="memdesc:a227b1cbbe91bcb21153c09f97d0dd484"><td class="mdescLeft">&#160;</td><td class="mdescRight">View the first byte of the buffer, without removing it from the <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> Buffer. <a href="#a227b1cbbe91bcb21153c09f97d0dd484">More...</a><br /></td></tr>
<tr class="separator:a227b1cbbe91bcb21153c09f97d0dd484"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a227b1cbbe91bcb21153c09f97d0dd484"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a51eb668f6a328a6a66298c6bc1361d41"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41">flush</a> ()</td></tr> <tr class="memitem:a51eb668f6a328a6a66298c6bc1361d41"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41">flush</a> ()</td></tr>
<tr class="memdesc:a51eb668f6a328a6a66298c6bc1361d41"><td class="mdescLeft">&#160;</td><td class="mdescRight">Force writing the buffered bytes from <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> to the network. This function is blocking until all bytes from the buffer are written. For an explanation of how writing with <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> works, please see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>. The implementation for this function can be found in SSLClientImpl::flush. <a href="#a51eb668f6a328a6a66298c6bc1361d41">More...</a><br /></td></tr> <tr class="memdesc:a51eb668f6a328a6a66298c6bc1361d41"><td class="mdescLeft">&#160;</td><td class="mdescRight">Force writing the buffered bytes from <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> to the network. <a href="#a51eb668f6a328a6a66298c6bc1361d41">More...</a><br /></td></tr>
<tr class="separator:a51eb668f6a328a6a66298c6bc1361d41"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a51eb668f6a328a6a66298c6bc1361d41"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a158d87df3fe118b7565a19b72f310322"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a158d87df3fe118b7565a19b72f310322">stop</a> ()</td></tr> <tr class="memitem:a158d87df3fe118b7565a19b72f310322"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a158d87df3fe118b7565a19b72f310322">stop</a> ()</td></tr>
<tr class="memdesc:a158d87df3fe118b7565a19b72f310322"><td class="mdescLeft">&#160;</td><td class="mdescRight">Close the connection If the SSL session is still active, all incoming data is discarded and BearSSL will attempt to close the session gracefully (will write to the network), and then call m_client::stop. If the session is not active or an error was encountered previously, this function will simply call m_client::stop. The implementation for this function can be found in SSLClientImpl::peek. <a href="#a158d87df3fe118b7565a19b72f310322">More...</a><br /></td></tr> <tr class="memdesc:a158d87df3fe118b7565a19b72f310322"><td class="mdescLeft">&#160;</td><td class="mdescRight">Close the connection. <a href="#a158d87df3fe118b7565a19b72f310322">More...</a><br /></td></tr>
<tr class="separator:a158d87df3fe118b7565a19b72f310322"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a158d87df3fe118b7565a19b72f310322"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="memItemLeft" align="right" valign="top">virtual uint8_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8">connected</a> ()</td></tr> <tr class="memitem:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="memItemLeft" align="right" valign="top">virtual uint8_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8">connected</a> ()</td></tr>
<tr class="memdesc:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Check if the device is connected. Use this function to determine if <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> is still connected and a SSL connection is active. It should be noted that <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> should be preferred over this function for rapid polling&ndash;both functions send and receive data with the SSLClient::m_client device, however <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> has some delays built in to protect SSLClient::m_client from being polled too frequently. <a href="#a7318aadc0ec9775bffaaac0b1f00aaf8">More...</a><br /></td></tr> <tr class="memdesc:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="mdescLeft">&#160;</td><td class="mdescRight">Check if the device is connected. <a href="#a7318aadc0ec9775bffaaac0b1f00aaf8">More...</a><br /></td></tr>
<tr class="separator:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a7318aadc0ec9775bffaaac0b1f00aaf8"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="memItemLeft" align="right" valign="top">virtual <a class="el" href="class_s_s_l_session.html">SSLSession</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae3f27a36ff9c0cd1e2bea5e1708b6e4f">getSession</a> (const char *host, const IPAddress &amp;addr)</td></tr> <tr class="memitem:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="memItemLeft" align="right" valign="top">virtual <a class="el" href="class_s_s_l_session.html">SSLSession</a> &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ae3f27a36ff9c0cd1e2bea5e1708b6e4f">getSession</a> (const char *host, const IPAddress &amp;addr)</td></tr>
<tr class="memdesc:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get a session reference corresponding to a host and IP, or a reference to a empty session if none exist. <a href="#ae3f27a36ff9c0cd1e2bea5e1708b6e4f">More...</a><br /></td></tr> <tr class="memdesc:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="mdescLeft">&#160;</td><td class="mdescRight">Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist. <a href="#ae3f27a36ff9c0cd1e2bea5e1708b6e4f">More...</a><br /></td></tr>
<tr class="separator:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ae3f27a36ff9c0cd1e2bea5e1708b6e4f"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a0000d7f1e8656cf4a506a98133391fe0"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a0000d7f1e8656cf4a506a98133391fe0">removeSession</a> (const char *host, const IPAddress &amp;addr)</td></tr> <tr class="memitem:a0000d7f1e8656cf4a506a98133391fe0"><td class="memItemLeft" align="right" valign="top">virtual void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a0000d7f1e8656cf4a506a98133391fe0">removeSession</a> (const char *host, const IPAddress &amp;addr)</td></tr>
<tr class="memdesc:a0000d7f1e8656cf4a506a98133391fe0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clear the session corresponding to a host and IP. <a href="#a0000d7f1e8656cf4a506a98133391fe0">More...</a><br /></td></tr> <tr class="memdesc:a0000d7f1e8656cf4a506a98133391fe0"><td class="mdescLeft">&#160;</td><td class="mdescRight">Clear the session corresponding to a host and IP. <a href="#a0000d7f1e8656cf4a506a98133391fe0">More...</a><br /></td></tr>
@ -157,17 +157,17 @@ Public Member Functions</h2></td></tr>
<tr class="memdesc:a36bb344866e4cbcba3bbfcf4d33e5187"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get the maximum number of SSL sessions that can be stored at once. <a href="#a36bb344866e4cbcba3bbfcf4d33e5187">More...</a><br /></td></tr> <tr class="memdesc:a36bb344866e4cbcba3bbfcf4d33e5187"><td class="mdescLeft">&#160;</td><td class="mdescRight">Get the maximum number of SSL sessions that can be stored at once. <a href="#a36bb344866e4cbcba3bbfcf4d33e5187">More...</a><br /></td></tr>
<tr class="separator:a36bb344866e4cbcba3bbfcf4d33e5187"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a36bb344866e4cbcba3bbfcf4d33e5187"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a319a722dae252efdd85fdbaf5c7fbf17"><td class="memItemLeft" align="right" valign="top">virtual&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a319a722dae252efdd85fdbaf5c7fbf17">operator bool</a> ()</td></tr> <tr class="memitem:a319a722dae252efdd85fdbaf5c7fbf17"><td class="memItemLeft" align="right" valign="top">virtual&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a319a722dae252efdd85fdbaf5c7fbf17">operator bool</a> ()</td></tr>
<tr class="memdesc:a319a722dae252efdd85fdbaf5c7fbf17"><td class="mdescLeft">&#160;</td><td class="mdescRight">Equivalent to <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected()</a> &gt; 0. <a href="#a319a722dae252efdd85fdbaf5c7fbf17">More...</a><br /></td></tr> <tr class="memdesc:a319a722dae252efdd85fdbaf5c7fbf17"><td class="mdescLeft">&#160;</td><td class="mdescRight">Equivalent to <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected()</a> &gt; 0. <a href="#a319a722dae252efdd85fdbaf5c7fbf17">More...</a><br /></td></tr>
<tr class="separator:a319a722dae252efdd85fdbaf5c7fbf17"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a319a722dae252efdd85fdbaf5c7fbf17"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a6fb2e8a1cc54dd82a72217e5c4533e02"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a6fb2e8a1cc54dd82a72217e5c4533e02">operator==</a> (const bool value)</td></tr> <tr class="memitem:a6fb2e8a1cc54dd82a72217e5c4533e02"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a6fb2e8a1cc54dd82a72217e5c4533e02">operator==</a> (const bool value)</td></tr>
<tr class="separator:a6fb2e8a1cc54dd82a72217e5c4533e02"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a6fb2e8a1cc54dd82a72217e5c4533e02"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a9a060e49d0685c6c6795558e41cd3323"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a9a060e49d0685c6c6795558e41cd3323">operator!=</a> (const bool value)</td></tr> <tr class="memitem:a9a060e49d0685c6c6795558e41cd3323"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a9a060e49d0685c6c6795558e41cd3323">operator!=</a> (const bool value)</td></tr>
<tr class="separator:a9a060e49d0685c6c6795558e41cd3323"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a9a060e49d0685c6c6795558e41cd3323"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a26f9418e33d4ca459f78de98d3af43bb"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a26f9418e33d4ca459f78de98d3af43bb">operator==</a> (const C &amp;rhs)</td></tr> <tr class="memitem:a26f9418e33d4ca459f78de98d3af43bb"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a26f9418e33d4ca459f78de98d3af43bb">operator==</a> (const C &amp;rhs)</td></tr>
<tr class="memdesc:a26f9418e33d4ca459f78de98d3af43bb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> objects have the same underlying client object. <a href="#a26f9418e33d4ca459f78de98d3af43bb">More...</a><br /></td></tr> <tr class="memdesc:a26f9418e33d4ca459f78de98d3af43bb"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> objects have the same underlying client object. <a href="#a26f9418e33d4ca459f78de98d3af43bb">More...</a><br /></td></tr>
<tr class="separator:a26f9418e33d4ca459f78de98d3af43bb"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a26f9418e33d4ca459f78de98d3af43bb"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a518f4ed733814f2f4a8c7f838555eb35"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a518f4ed733814f2f4a8c7f838555eb35">operator!=</a> (const C &amp;rhs)</td></tr> <tr class="memitem:a518f4ed733814f2f4a8c7f838555eb35"><td class="memItemLeft" align="right" valign="top">virtual bool&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a518f4ed733814f2f4a8c7f838555eb35">operator!=</a> (const C &amp;rhs)</td></tr>
<tr class="memdesc:a518f4ed733814f2f4a8c7f838555eb35"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> objects do not have the same underlying client object. <a href="#a518f4ed733814f2f4a8c7f838555eb35">More...</a><br /></td></tr> <tr class="memdesc:a518f4ed733814f2f4a8c7f838555eb35"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> objects do not have the same underlying client object. <a href="#a518f4ed733814f2f4a8c7f838555eb35">More...</a><br /></td></tr>
<tr class="separator:a518f4ed733814f2f4a8c7f838555eb35"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a518f4ed733814f2f4a8c7f838555eb35"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ac725067566ee411680c88575c148300b"><td class="memItemLeft" align="right" valign="top">virtual uint16_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b">localPort</a> ()</td></tr> <tr class="memitem:ac725067566ee411680c88575c148300b"><td class="memItemLeft" align="right" valign="top">virtual uint16_t&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b">localPort</a> ()</td></tr>
<tr class="memdesc:ac725067566ee411680c88575c148300b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the local port, C::localPort exists. Else return 0. <a href="#ac725067566ee411680c88575c148300b">More...</a><br /></td></tr> <tr class="memdesc:ac725067566ee411680c88575c148300b"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the local port, C::localPort exists. Else return 0. <a href="#ac725067566ee411680c88575c148300b">More...</a><br /></td></tr>
@ -179,7 +179,7 @@ Public Member Functions</h2></td></tr>
<tr class="memdesc:ae8bd9420fec3b11f855729c4ecfe1c2c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the remote port, if C::remotePort exists. Else return 0. <a href="#ae8bd9420fec3b11f855729c4ecfe1c2c">More...</a><br /></td></tr> <tr class="memdesc:ae8bd9420fec3b11f855729c4ecfe1c2c"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns the remote port, if C::remotePort exists. Else return 0. <a href="#ae8bd9420fec3b11f855729c4ecfe1c2c">More...</a><br /></td></tr>
<tr class="separator:ae8bd9420fec3b11f855729c4ecfe1c2c"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ae8bd9420fec3b11f855729c4ecfe1c2c"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:afd0d4d2c98433d60897d8828d8047d41"><td class="memItemLeft" align="right" valign="top">C &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#afd0d4d2c98433d60897d8828d8047d41">getClient</a> ()</td></tr> <tr class="memitem:afd0d4d2c98433d60897d8828d8047d41"><td class="memItemLeft" align="right" valign="top">C &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#afd0d4d2c98433d60897d8828d8047d41">getClient</a> ()</td></tr>
<tr class="memdesc:afd0d4d2c98433d60897d8828d8047d41"><td class="mdescLeft">&#160;</td><td class="mdescRight">returns a reference to the client object stored in this class. Take care not to break it. <a href="#afd0d4d2c98433d60897d8828d8047d41">More...</a><br /></td></tr> <tr class="memdesc:afd0d4d2c98433d60897d8828d8047d41"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns a reference to the client object stored in this class. Take care not to break it. <a href="#afd0d4d2c98433d60897d8828d8047d41">More...</a><br /></td></tr>
<tr class="separator:afd0d4d2c98433d60897d8828d8047d41"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:afd0d4d2c98433d60897d8828d8047d41"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="inherit_header pub_methods_class_s_s_l_client_impl"><td colspan="2" onclick="javascript:toggleInherit('pub_methods_class_s_s_l_client_impl')"><img src="closed.png" alt="-"/>&#160;Public Member Functions inherited from <a class="el" href="class_s_s_l_client_impl.html">SSLClientImpl</a></td></tr> <tr class="inherit_header pub_methods_class_s_s_l_client_impl"><td colspan="2" onclick="javascript:toggleInherit('pub_methods_class_s_s_l_client_impl')"><img src="closed.png" alt="-"/>&#160;Public Member Functions inherited from <a class="el" href="class_s_s_l_client_impl.html">SSLClientImpl</a></td></tr>
<tr class="memitem:a2b0b9043c8252871272bf6ba199ab67b inherit pub_methods_class_s_s_l_client_impl"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client_impl.html#a2b0b9043c8252871272bf6ba199ab67b">SSLClientImpl</a> (const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">DebugLevel</a> debug)</td></tr> <tr class="memitem:a2b0b9043c8252871272bf6ba199ab67b inherit pub_methods_class_s_s_l_client_impl"><td class="memItemLeft" align="right" valign="top">&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client_impl.html#a2b0b9043c8252871272bf6ba199ab67b">SSLClientImpl</a> (const br_x509_trust_anchor *trust_anchors, const size_t trust_anchors_num, const int analog_pin, const <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395">DebugLevel</a> debug)</td></tr>
@ -210,12 +210,12 @@ Public Member Functions</h2></td></tr>
<tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pro-methods"></a> <tr class="heading"><td colspan="2"><h2 class="groupheader"><a name="pro-methods"></a>
Protected Member Functions</h2></td></tr> Protected Member Functions</h2></td></tr>
<tr class="memitem:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="memItemLeft" align="right" valign="top">virtual Client &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106">get_arduino_client</a> ()</td></tr> <tr class="memitem:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="memItemLeft" align="right" valign="top">virtual Client &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106">get_arduino_client</a> ()</td></tr>
<tr class="memdesc:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="mdescLeft">&#160;</td><td class="mdescRight">return an instance of m_client that is polymorphic and can be used by <a class="el" href="class_s_s_l_client_impl.html" title="Implementation code to be inherited by SSLClient.">SSLClientImpl</a> <a href="#ab3ebfbca41a56bfa11e34aac2c2e0106">More...</a><br /></td></tr> <tr class="memdesc:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns an instance of m_client that is polymorphic and can be used by <a class="el" href="class_s_s_l_client_impl.html" title="Implementation code to be inherited by SSLClient.">SSLClientImpl</a>. <a href="#ab3ebfbca41a56bfa11e34aac2c2e0106">More...</a><br /></td></tr>
<tr class="separator:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ab3ebfbca41a56bfa11e34aac2c2e0106"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a20742b36588c45435139a4f47fe0f1f6"><td class="memItemLeft" align="right" valign="top">virtual const Client &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a20742b36588c45435139a4f47fe0f1f6">get_arduino_client</a> () const</td></tr> <tr class="memitem:a20742b36588c45435139a4f47fe0f1f6"><td class="memItemLeft" align="right" valign="top">virtual const Client &amp;&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#a20742b36588c45435139a4f47fe0f1f6">get_arduino_client</a> () const</td></tr>
<tr class="separator:a20742b36588c45435139a4f47fe0f1f6"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a20742b36588c45435139a4f47fe0f1f6"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="memItemLeft" align="right" valign="top">virtual <a class="el" href="class_s_s_l_session.html">SSLSession</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51">get_session_array</a> ()</td></tr> <tr class="memitem:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="memItemLeft" align="right" valign="top">virtual <a class="el" href="class_s_s_l_session.html">SSLSession</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51">get_session_array</a> ()</td></tr>
<tr class="memdesc:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="mdescLeft">&#160;</td><td class="mdescRight">return an instance of the session array that is on the stack <a href="#aaa52b481eb1d36a0ae1d208daa2fec51">More...</a><br /></td></tr> <tr class="memdesc:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns an instance of the session array that is on the stack. <a href="#aaa52b481eb1d36a0ae1d208daa2fec51">More...</a><br /></td></tr>
<tr class="separator:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:aaa52b481eb1d36a0ae1d208daa2fec51"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:ab076a76b142b553c0dfd29174d4e17e7"><td class="memItemLeft" align="right" valign="top">virtual const <a class="el" href="class_s_s_l_session.html">SSLSession</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ab076a76b142b553c0dfd29174d4e17e7">get_session_array</a> () const</td></tr> <tr class="memitem:ab076a76b142b553c0dfd29174d4e17e7"><td class="memItemLeft" align="right" valign="top">virtual const <a class="el" href="class_s_s_l_session.html">SSLSession</a> *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_client.html#ab076a76b142b553c0dfd29174d4e17e7">get_session_array</a> () const</td></tr>
<tr class="separator:ab076a76b142b553c0dfd29174d4e17e7"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ab076a76b142b553c0dfd29174d4e17e7"><td class="memSeparator" colspan="2">&#160;</td></tr>
@ -248,7 +248,7 @@ Protected Member Functions</h2></td></tr>
<div class="textblock"><h3>template&lt;class C, size_t SessionCache = 1&gt;<br /> <div class="textblock"><h3>template&lt;class C, size_t SessionCache = 1&gt;<br />
class SSLClient&lt; C, SessionCache &gt;</h3> class SSLClient&lt; C, SessionCache &gt;</h3>
<p>The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> class Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info. </p> <p>The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> class. Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info. </p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2> </div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="ae9a7509bc8a18f67e286547c19deb3c0"></a> <a id="ae9a7509bc8a18f67e286547c19deb3c0"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae9a7509bc8a18f67e286547c19deb3c0">&#9670;&nbsp;</a></span>SSLClient()</h2> <h2 class="memtitle"><span class="permalink"><a href="#ae9a7509bc8a18f67e286547c19deb3c0">&#9670;&nbsp;</a></span>SSLClient()</h2>
@ -304,13 +304,13 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Initialize <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> with all of the prerequisites needed. </p> <p>Initialize <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> with all of the prerequisites needed. </p>
<dl class="section pre"><dt>Precondition</dt><dd>You will need to generate an array of trust_anchors (root certificates) based off of the domains you want to make SSL connections to. Check out the <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> file for more info. </dd> <dl class="section pre"><dt>Precondition</dt><dd>You will need to generate an array of trust_anchors (root certificates) based off of the domains you want to make SSL connections to. Check out the <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> file for more info. </dd>
<dd> <dd>
The analog_pin should be set to input.</dd></dl> The analog_pin should be set to input.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
<table class="params"> <table class="params">
<tr><td class="paramname">client</td><td>The base network device to create an SSL socket on. This object will be copied and the copy will be stored in <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. </td></tr> <tr><td class="paramname">client</td><td>The base network device to create an SSL socket on. This object will be copied and the copy will be stored in <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>. </td></tr>
<tr><td class="paramname">trust_anchors</td><td>Trust anchors used in the verification of the SSL server certificate. Check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> for more info. </td></tr> <tr><td class="paramname">trust_anchors</td><td>Trust anchors used in the verification of the SSL server certificate. Check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> for more info. </td></tr>
<tr><td class="paramname">trust_anchors_num</td><td>The number of objects in the trust_anchors array. </td></tr> <tr><td class="paramname">trust_anchors_num</td><td>The number of objects in the trust_anchors array. </td></tr>
<tr><td class="paramname">analog_pin</td><td>An analog pin to pull random bytes from, used in seeding the RNG. </td></tr> <tr><td class="paramname">analog_pin</td><td>An analog pin to pull random bytes from, used in seeding the RNG. </td></tr>
@ -347,10 +347,10 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Returns the number of bytes availible to read from the SSL Socket. </p> <p>Returns the number of bytes available to read from the data that has been received and decrypted. </p>
<p>This function updates the state of the SSL engine (including writing any data, see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>) and as a result should be called periodically when expecting data. Additionally, since if there are no bytes and if <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected</a> is false this function returns zero (this same behavior is found in EthernetClient), it is prudent to ensure in your own code that the preconditions are met before checking this function to prevent an ambiguous result.</p> <p>This function updates the state of the SSL engine (including writing any data, see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>) and as a result should be called periodically when expecting data. Additionally, since if there are no bytes and if <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected</a> is false this function returns zero (this same behavior is found in EthernetClient), it is prudent to ensure in your own code that the preconditions are met before checking this function to prevent an ambiguous result.</p>
<p>The implementation for this function can be found in SSLClientImpl::available</p> <p>The implementation for this function can be found in SSLClientImpl::available</p>
<dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected</a> must be true.</dd></dl> <dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected</a> must be true.</dd></dl>
<dl class="section return"><dt>Returns</dt><dd>The number of bytes available (can be zero), or zero if any of the pre conditions aren't satisfied. </dd></dl> <dl class="section return"><dt>Returns</dt><dd>The number of bytes available (can be zero), or zero if any of the pre conditions aren't satisfied. </dd></dl>
</div> </div>
@ -392,15 +392,15 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Connect over SSL to a host specified by an IP address. </p> <p>Connect over SSL to a host specified by an IP address. </p>
<p>SSLClient::connect(host, port) should be preferred over this function, as verifying the domain name is a step in ensuring the certificate is legitimate, which is important to the security of the device. Additionally, SSL sessions cannot be resumed, which can drastically increase initial connect time.</p> <p>SSLClient::connect(host, port) should be preferred over this function, as verifying the domain name is a step in ensuring the certificate is legitimate, which is important to the security of the device. Additionally, SSL sessions cannot be resumed when using this function, which can drastically increase initial connect time.</p>
<p>This function initializes the socket by calling m_client::connect(IPAddress, uint16_t) with the parameters supplied, then once the socket uses BearSSL to to complete a SSL handshake. Due to the design of the SSL standard, this function will probably take an extended period (1-4sec) to negotiate the handshake and finish the connection. This function runs until the SSL handshake succeeds or fails.</p> <p>This function initializes the socket by calling m_client::connect(IPAddress, uint16_t) with the parameters supplied, then once the socket is open, uses BearSSL to to complete a SSL handshake. Due to the design of the SSL standard, this function will probably take an extended period (1-4sec) to negotiate the handshake and finish the connection. This function runs until the SSL handshake succeeds or fails.</p>
<p>SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.</p> <p>SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.</p>
<p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#aa5c14ecf301c268306946c85825e565b">SSLClientImpl::connect_impl(IPAddress, uint16_t)</a>.</p> <p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#aa5c14ecf301c268306946c85825e565b">SSLClientImpl::connect_impl(IPAddress, uint16_t)</a>.</p>
<dl class="section pre"><dt>Precondition</dt><dd>The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP. </dd> <dl class="section pre"><dt>Precondition</dt><dd>The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP. </dd>
<dd> <dd>
<a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> can only have one connection at a time, so the client object must not already be connected. </dd> <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> can only have one connection at a time, so the client object must not already be connected. </dd>
<dd> <dd>
There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> will fail). </dd> There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> will fail). </dd>
<dd> <dd>
There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> .</dd></dl> There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> .</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
@ -451,15 +451,15 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Connect over SSL to a host specified by a hostname. </p> <p>Connect over SSL to a host specified by a hostname. </p>
<p>This function initializes the socket by calling m_client::connect(const char*, uint16_t) with the parameters supplied, then once the socket is open uses BearSSL to to complete a SSL handshake. This function runs until the SSL handshake succeeds or fails.</p> <p>This function initializes the socket by calling m_client::connect(const char*, uint16_t) with the parameters supplied, then once the socket is open, uses BearSSL to complete a SSL handshake. This function runs until the SSL handshake succeeds or fails.</p>
<p>SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.</p> <p>SSL requires the client to generate some random bits (to be later combined with some random bits from the server), so <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> uses the least significant bits from the analog pin supplied in the constructor. The random bits are generated from 16 consecutive analogReads, and given to BearSSL before the handshake starts.</p>
<p>This function will usually take around 4-10 seconds. If possible, this function also attempts to resume the SSL session if one is present matching the hostname string, which will reduce connection time to 100-500ms. To read more about this functionality, check out Session Caching in the README.</p> <p>This function will usually take around 4-10 seconds. If possible, this function also attempts to resume the SSL session if one is present matching the hostname string, which will reduce connection time to 100-500ms. To read more about this functionality, check out Session Caching in the README.</p>
<p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#ae6c947ad92979ab99364428004abbeba">SSLClientImpl::connect_impl(const char*, uint16_t)</a></p> <p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#ae6c947ad92979ab99364428004abbeba">SSLClientImpl::connect_impl(const char*, uint16_t)</a></p>
<dl class="section pre"><dt>Precondition</dt><dd>The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP. </dd> <dl class="section pre"><dt>Precondition</dt><dd>The underlying client object (passed in through the constructor) is in a non- error state, and must be able to access the IP. </dd>
<dd> <dd>
<a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> can only have one connection at a time, so the client object must not already be connected. </dd> <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> can only have one connection at a time, so the client object must not already be connected. </dd>
<dd> <dd>
There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> will fail). </dd> There must be sufficient memory available on the device to verify the certificate (if the free memory drops below 8000 bytes during certain points in the connection, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> will fail). </dd>
<dd> <dd>
There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> .</dd></dl> There must be a trust anchor given to the constructor that corresponds to the certificate provided by the IP address being connected to. For more information check out <a class="el" href="_trust_anchors_8md.html">TrustAnchors.md</a> .</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
@ -498,7 +498,8 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Check if the device is connected. Use this function to determine if <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> is still connected and a SSL connection is active. It should be noted that <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> should be preferred over this function for rapid polling&ndash;both functions send and receive data with the SSLClient::m_client device, however <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> has some delays built in to protect SSLClient::m_client from being polled too frequently. </p> <p>Check if the device is connected. </p>
<p>Use this function to determine if <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is still connected and a SSL connection is active. It should be noted that <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> should be preferred over this function for rapid polling&ndash;both functions send and receive data with the SSLClient::m_client device, however <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> has some delays built in to protect SSLClient::m_client from being polled too frequently.</p>
<p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a957984fa392550a7df86f758e9b14bfb">SSLClientImpl::connected_impl</a>.</p> <p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a957984fa392550a7df86f758e9b14bfb">SSLClientImpl::connected_impl</a>.</p>
<dl class="section return"><dt>Returns</dt><dd>1 if connected, 0 if not </dd></dl> <dl class="section return"><dt>Returns</dt><dd>1 if connected, 0 if not </dd></dl>
@ -529,7 +530,8 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Force writing the buffered bytes from <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> to the network. This function is blocking until all bytes from the buffer are written. For an explanation of how writing with <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> works, please see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>. The implementation for this function can be found in SSLClientImpl::flush. </p> <p>Force writing the buffered bytes from <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> to the network. </p>
<p>This function is blocking until all bytes from the buffer are written. For an explanation of how writing with <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> works, please see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>. The implementation for this function can be found in SSLClientImpl::flush. </p>
</div> </div>
</div> </div>
@ -558,7 +560,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>return an instance of m_client that is polymorphic and can be used by <a class="el" href="class_s_s_l_client_impl.html" title="Implementation code to be inherited by SSLClient.">SSLClientImpl</a> </p> <p>Returns an instance of m_client that is polymorphic and can be used by <a class="el" href="class_s_s_l_client_impl.html" title="Implementation code to be inherited by SSLClient.">SSLClientImpl</a>. </p>
<p>Implements <a class="el" href="class_s_s_l_client_impl.html#a20dd9a9794b95719e6f3df8cb39126e3">SSLClientImpl</a>.</p> <p>Implements <a class="el" href="class_s_s_l_client_impl.html#a20dd9a9794b95719e6f3df8cb39126e3">SSLClientImpl</a>.</p>
@ -618,7 +620,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>return an instance of the session array that is on the stack </p> <p>Returns an instance of the session array that is on the stack. </p>
<p>Implements <a class="el" href="class_s_s_l_client_impl.html#a44cfafd6f5cdcaa5dbac22961ab3a58b">SSLClientImpl</a>.</p> <p>Implements <a class="el" href="class_s_s_l_client_impl.html#a44cfafd6f5cdcaa5dbac22961ab3a58b">SSLClientImpl</a>.</p>
@ -678,7 +680,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>returns a reference to the client object stored in this class. Take care not to break it. </p> <p>Returns a reference to the client object stored in this class. Take care not to break it. </p>
</div> </div>
</div> </div>
@ -718,7 +720,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Get a session reference corresponding to a host and IP, or a reference to a empty session if none exist. </p> <p>Gets a session reference corresponding to a host and IP, or a reference to a empty session if none exist. </p>
<p>If no session corresponding to the host and IP exist, then this function will cycle through sessions in a rotating order. This allows the session cache to continually store sessions, however it will also result in old sessions being cleared and returned. In general, it is a good idea to use a SessionCache size equal to the number of domains you plan on connecting to.</p> <p>If no session corresponding to the host and IP exist, then this function will cycle through sessions in a rotating order. This allows the session cache to continually store sessions, however it will also result in old sessions being cleared and returned. In general, it is a good idea to use a SessionCache size equal to the number of domains you plan on connecting to.</p>
<p>The implementation for this function can be found at <a class="el" href="class_s_s_l_client_impl.html#ab4e38d4319ec504395d67d2ab21a639e">SSLClientImpl::get_session_impl</a>.</p> <p>The implementation for this function can be found at <a class="el" href="class_s_s_l_client_impl.html#ab4e38d4319ec504395d67d2ab21a639e">SSLClientImpl::get_session_impl</a>.</p>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
@ -820,7 +822,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Equivalent to <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected()</a> &gt; 0. </p> <p>Equivalent to <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected()</a> &gt; 0. </p>
<dl class="section return"><dt>Returns</dt><dd>true if connected, false if not </dd></dl> <dl class="section return"><dt>Returns</dt><dd>true if connected, false if not </dd></dl>
</div> </div>
@ -880,7 +882,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> objects do not have the same underlying client object. </p> <p>Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> objects do not have the same underlying client object. </p>
</div> </div>
</div> </div>
@ -939,7 +941,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> objects have the same underlying client object. </p> <p>Returns whether or not two <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> objects have the same underlying client object. </p>
</div> </div>
</div> </div>
@ -968,8 +970,8 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>view the first byte of the buffer, without removing it from the <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> Buffer The implementation for this function can be found in SSLClientImpl::peek </p> <p>View the first byte of the buffer, without removing it from the <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> Buffer. </p>
<dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> must be &gt;0 </dd></dl> <p>The implementation for this function can be found in SSLClientImpl::peek </p><dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> must be &gt;0 </dd></dl>
<dl class="section return"><dt>Returns</dt><dd>The first byte received, or -1 if the preconditions are not satisfied (warning: do not use if your data may be -1, as the return value is ambiguous) </dd></dl> <dl class="section return"><dt>Returns</dt><dd>The first byte received, or -1 if the preconditions are not satisfied (warning: do not use if your data may be -1, as the return value is ambiguous) </dd></dl>
</div> </div>
@ -1000,7 +1002,7 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Read a single byte, or -1 if none is available. </p> <p>Read a single byte, or -1 if none is available. </p>
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf" title="Read size bytes from the SSL socket buffer, copying them into *buf, and return the number of bytes re...">SSLClient::read(uint8_t*, size_t)</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf" title="Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes re...">SSLClient::read(uint8_t*, size_t)</a> </dd></dl>
</div> </div>
</div> </div>
@ -1040,11 +1042,11 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Read size bytes from the SSL socket buffer, copying them into *buf, and return the number of bytes read. </p> <p>Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes read. </p>
<p>This function checks if bytes are ready to be read by calling <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a>, and if so copies size number of bytes from the IO buffer into the buf pointer. Data read using this function will not include any SSL or socket commands, as the Client and BearSSL will capture those and process them separately.</p> <p>This function checks if bytes are ready to be read by calling <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>, and if so copies size number of bytes from the IO buffer into the buf pointer. Data read using this function will not include any SSL or socket commands, as the Client and BearSSL will capture those and process them separately.</p>
<p>If you find that you are having a lot of timeout errors, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> may be experiencing a buffer overflow. Checkout <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more information.</p> <p>If you find that you are having a lot of timeout errors, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> may be experiencing a buffer overflow. Checkout <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more information.</p>
<p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a231b7b1bb2182cda1ed6e9d5ebf66afe">SSLClientImpl::read_impl(uint8_t*, size_t)</a></p> <p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a231b7b1bb2182cda1ed6e9d5ebf66afe">SSLClientImpl::read_impl(uint8_t*, size_t)</a></p>
<dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> must be &gt;0</dd></dl> <dl class="section pre"><dt>Precondition</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> must be &gt;0</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
<table class="params"> <table class="params">
<tr><td class="paramname">buf</td><td>The pointer to the buffer to put SSL application data into </td></tr> <tr><td class="paramname">buf</td><td>The pointer to the buffer to put SSL application data into </td></tr>
@ -1191,7 +1193,8 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Close the connection If the SSL session is still active, all incoming data is discarded and BearSSL will attempt to close the session gracefully (will write to the network), and then call m_client::stop. If the session is not active or an error was encountered previously, this function will simply call m_client::stop. The implementation for this function can be found in SSLClientImpl::peek. </p> <p>Close the connection. </p>
<p>If the SSL session is still active, all incoming data is discarded and BearSSL will attempt to close the session gracefully (will write to the network), and then call m_client::stop. If the session is not active or an error was encountered previously, this function will simply call m_client::stop. The implementation for this function can be found in SSLClientImpl::peek. </p>
</div> </div>
</div> </div>
@ -1261,9 +1264,9 @@ template&lt;class C , size_t SessionCache = 1&gt; </div>
</div><div class="memdoc"> </div><div class="memdoc">
<p>Write some bytes to the SSL connection. </p> <p>Write some bytes to the SSL connection. </p>
<p>Assuming all preconditions are met, this function writes data to the BearSSL IO buffer, BUT does not initially send the data. Instead, you must call <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> or <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network. This function is blocking unti...">SSLClient::flush</a>, which will detect that the buffer is ready for writing, and will write the data to the network. Alternatively, if this function is requested to write a larger amount of data than SSLClientImpl::m_iobuf can handle, data will be written to the network in pages the size of SSLClientImpl::m_iobuf until all the data in buf is sent&ndash;attempting to keep all writes to the network grouped together. For information on why this is the case check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> .</p> <p>Assuming all preconditions are met, this function writes data to the BearSSL IO buffer, BUT does not initially send the data. Instead, you must call <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> or <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will detect that the buffer is ready for writing, and will write the data to the network. Alternatively, if this function is requested to write a larger amount of data than SSLClientImpl::m_iobuf can handle, data will be written to the network in pages the size of SSLClientImpl::m_iobuf until all the data in buf is sent&ndash;attempting to keep all writes to the network grouped together. For information on why this is the case check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> .</p>
<p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a807656f814f24cf6cd711e429b716c4d">SSLClientImpl::write_impl(const uint8_t*, size_t)</a></p> <p>The implementation for this function can be found in <a class="el" href="class_s_s_l_client_impl.html#a807656f814f24cf6cd711e429b716c4d">SSLClientImpl::write_impl(const uint8_t*, size_t)</a></p>
<dl class="section pre"><dt>Precondition</dt><dd>The socket and SSL layer must be connected, meaning <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected</a> must be true. </dd> <dl class="section pre"><dt>Precondition</dt><dd>The socket and SSL layer must be connected, meaning <a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected</a> must be true. </dd>
<dd> <dd>
BearSSL must not be waiting for the recipt of user data (if it is, there is probably an error with how the protocol in implemented in your code).</dd></dl> BearSSL must not be waiting for the recipt of user data (if it is, there is probably an error with how the protocol in implemented in your code).</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>

36
docs/html/class_s_s_l_client_impl.html
View file

@ -96,7 +96,7 @@ $(document).ready(function(){initNavTree('class_s_s_l_client_impl.html','');});
</div><!--header--> </div><!--header-->
<div class="contents"> <div class="contents">
<p>Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. <p>Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>.
<a href="class_s_s_l_client_impl.html#details">More...</a></p> <a href="class_s_s_l_client_impl.html#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="_s_s_l_client_impl_8h_source.html">SSLClientImpl.h</a>&gt;</code></p> <p><code>#include &lt;<a class="el" href="_s_s_l_client_impl_8h_source.html">SSLClientImpl.h</a>&gt;</code></p>
@ -106,7 +106,7 @@ Inheritance diagram for SSLClientImpl:</div>
<div class="center"> <div class="center">
<img src="class_s_s_l_client_impl.png" usemap="#SSLClientImpl_map" alt=""/> <img src="class_s_s_l_client_impl.png" usemap="#SSLClientImpl_map" alt=""/>
<map id="SSLClientImpl_map" name="SSLClientImpl_map"> <map id="SSLClientImpl_map" name="SSLClientImpl_map">
<area href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info." alt="SSLClient&lt; C, SessionCache &gt;" shape="rect" coords="0,112,190,136"/> <area href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info." alt="SSLClient&lt; C, SessionCache &gt;" shape="rect" coords="0,112,190,136"/>
</map> </map>
</div></div> </div></div>
<table class="memberdecls"> <table class="memberdecls">
@ -180,7 +180,7 @@ Protected Member Functions</h2></td></tr>
<tr class="separator:ada595ed8f11673a9180ef0b762949c83"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:ada595ed8f11673a9180ef0b762949c83"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table> </table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a>. </p> <div class="textblock"><p>Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>. </p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2> </div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="a2b0b9043c8252871272bf6ba199ab67b"></a> <a id="a2b0b9043c8252871272bf6ba199ab67b"></a>
<h2 class="memtitle"><span class="permalink"><a href="#a2b0b9043c8252871272bf6ba199ab67b">&#9670;&nbsp;</a></span>SSLClientImpl()</h2> <h2 class="memtitle"><span class="permalink"><a href="#a2b0b9043c8252871272bf6ba199ab67b">&#9670;&nbsp;</a></span>SSLClientImpl()</h2>
@ -227,7 +227,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0" title="Initialize SSLClient with all of the prerequisites needed.">SSLClient::SSLClient</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0" title="Initialize SSLClient with all of the prerequisites needed.">SSLClient::SSLClient</a> </dd></dl>
</div> </div>
</div> </div>
@ -246,7 +246,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes availible to read from the SSL Socket.">SSLClient::available</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> </dd></dl>
</div> </div>
</div> </div>
@ -322,7 +322,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected. Use this function to determine if SSLClient is still connected and ...">SSLClient::connected</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a7318aadc0ec9775bffaaac0b1f00aaf8" title="Check if the device is connected.">SSLClient::connected</a> </dd></dl>
</div> </div>
</div> </div>
@ -340,7 +340,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network. This function is blocking unti...">SSLClient::flush</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a> </dd></dl>
</div> </div>
</div> </div>
@ -366,7 +366,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106" title="return an instance of m_client that is polymorphic and can be used by SSLClientImpl">SSLClient::get_arduino_client</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106" title="Returns an instance of m_client that is polymorphic and can be used by SSLClientImpl.">SSLClient::get_arduino_client</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#ab3ebfbca41a56bfa11e34aac2c2e0106">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -421,7 +421,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51" title="return an instance of the session array that is on the stack">SSLClient::get_session_array</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51" title="Returns an instance of the session array that is on the stack.">SSLClient::get_session_array</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#aaa52b481eb1d36a0ae1d208daa2fec51">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -479,7 +479,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ae3f27a36ff9c0cd1e2bea5e1708b6e4f" title="Get a session reference corresponding to a host and IP, or a reference to a empty session if none exi...">SSLClient::getSession</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae3f27a36ff9c0cd1e2bea5e1708b6e4f" title="Gets a session reference corresponding to a host and IP, or a reference to a empty session if none ex...">SSLClient::getSession</a> </dd></dl>
</div> </div>
</div> </div>
@ -505,7 +505,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#a36bb344866e4cbcba3bbfcf4d33e5187" title="Get the maximum number of SSL sessions that can be stored at once.">SSLClient::getSessionCount</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a36bb344866e4cbcba3bbfcf4d33e5187" title="Get the maximum number of SSL sessions that can be stored at once.">SSLClient::getSessionCount</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#a36bb344866e4cbcba3bbfcf4d33e5187">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#a36bb344866e4cbcba3bbfcf4d33e5187">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -533,7 +533,7 @@ Protected Member Functions</h2></td></tr>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b" title="Returns the local port, C::localPort exists. Else return 0.">SSLClient::localPort</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b" title="Returns the local port, C::localPort exists. Else return 0.">SSLClient::localPort</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -829,7 +829,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a227b1cbbe91bcb21153c09f97d0dd484" title="view the first byte of the buffer, without removing it from the SSLClient Buffer The implementation f...">SSLClient::peek</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a227b1cbbe91bcb21153c09f97d0dd484" title="View the first byte of the buffer, without removing it from the SSLClient Buffer.">SSLClient::peek</a> </dd></dl>
</div> </div>
</div> </div>
@ -858,7 +858,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf" title="Read size bytes from the SSL socket buffer, copying them into *buf, and return the number of bytes re...">SSLClient::read(uint8_t*, size_t)</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae31dd88a1af8ec3794fb48f26a3dd4bf" title="Read size bytes from the SSL client buffer, copying them into *buf, and return the number of bytes re...">SSLClient::read(uint8_t*, size_t)</a> </dd></dl>
</div> </div>
</div> </div>
@ -884,7 +884,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ae2d1d17ee568ec2a37756bf6894dcd05" title="Returns the remote IP, if C::remoteIP exists. Else return INADDR_NONE.">SSLClient::remoteIP</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ae2d1d17ee568ec2a37756bf6894dcd05" title="Returns the remote IP, if C::remoteIP exists. Else return INADDR_NONE.">SSLClient::remoteIP</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#ae2d1d17ee568ec2a37756bf6894dcd05">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#ae2d1d17ee568ec2a37756bf6894dcd05">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -912,7 +912,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b" title="Returns the local port, C::localPort exists. Else return 0.">SSLClient::localPort</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#ac725067566ee411680c88575c148300b" title="Returns the local port, C::localPort exists. Else return 0.">SSLClient::localPort</a> </dd></dl>
<p>Implemented in <a class="el" href="class_s_s_l_client.html#ae8bd9420fec3b11f855729c4ecfe1c2c">SSLClient&lt; C, SessionCache &gt;</a>.</p> <p>Implemented in <a class="el" href="class_s_s_l_client.html#ae8bd9420fec3b11f855729c4ecfe1c2c">SSLClient&lt; C, SessionCache &gt;</a>.</p>
@ -943,7 +943,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>See <a class="el" href="class_s_s_l_client.html#a0000d7f1e8656cf4a506a98133391fe0" title="Clear the session corresponding to a host and IP.">SSLClient::removeSession</a> </p> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a0000d7f1e8656cf4a506a98133391fe0" title="Clear the session corresponding to a host and IP.">SSLClient::removeSession</a> </dd></dl>
</div> </div>
</div> </div>
@ -961,7 +961,7 @@ template&lt;typename T &gt; </div>
</tr> </tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a158d87df3fe118b7565a19b72f310322" title="Close the connection If the SSL session is still active, all incoming data is discarded and BearSSL w...">SSLClient::stop</a> </dd></dl> <dl class="section see"><dt>See also</dt><dd><a class="el" href="class_s_s_l_client.html#a158d87df3fe118b7565a19b72f310322" title="Close the connection.">SSLClient::stop</a> </dd></dl>
</div> </div>
</div> </div>

21
docs/html/class_s_s_l_session.html
View file

@ -95,7 +95,7 @@ $(document).ready(function(){initNavTree('class_s_s_l_session.html','');});
</div><!--header--> </div><!--header-->
<div class="contents"> <div class="contents">
<p>This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions. <p>This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions.
<a href="class_s_s_l_session.html#details">More...</a></p> <a href="class_s_s_l_session.html#details">More...</a></p>
<p><code>#include &lt;<a class="el" href="_s_s_l_session_8h_source.html">SSLSession.h</a>&gt;</code></p> <p><code>#include &lt;<a class="el" href="_s_s_l_session_8h_source.html">SSLSession.h</a>&gt;</code></p>
@ -126,17 +126,17 @@ Public Member Functions</h2></td></tr>
<tr class="memdesc:a2fa15ce0b7caae25dfb567954175257e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Set the ip address and hostname of the session. <a href="#a2fa15ce0b7caae25dfb567954175257e">More...</a><br /></td></tr> <tr class="memdesc:a2fa15ce0b7caae25dfb567954175257e"><td class="mdescLeft">&#160;</td><td class="mdescRight">Set the ip address and hostname of the session. <a href="#a2fa15ce0b7caae25dfb567954175257e">More...</a><br /></td></tr>
<tr class="separator:a2fa15ce0b7caae25dfb567954175257e"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a2fa15ce0b7caae25dfb567954175257e"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:a3305941fa615f7134526b718917716ee"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html#a3305941fa615f7134526b718917716ee">clear_parameters</a> ()</td></tr> <tr class="memitem:a3305941fa615f7134526b718917716ee"><td class="memItemLeft" align="right" valign="top">void&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html#a3305941fa615f7134526b718917716ee">clear_parameters</a> ()</td></tr>
<tr class="memdesc:a3305941fa615f7134526b718917716ee"><td class="mdescLeft">&#160;</td><td class="mdescRight">delete the parameters and invalidate the session Roughly equivalent to this_session = <a class="el" href="class_s_s_l_session.html#ae05648200cea66577f024d5d09a6fcbb" title="SSLSession constructor.">SSLSession()</a>, however this function preserves the String object, allowing it to better handle the dynamic memory needed. <a href="#a3305941fa615f7134526b718917716ee">More...</a><br /></td></tr> <tr class="memdesc:a3305941fa615f7134526b718917716ee"><td class="mdescLeft">&#160;</td><td class="mdescRight">Delete the parameters and invalidate the session. <a href="#a3305941fa615f7134526b718917716ee">More...</a><br /></td></tr>
<tr class="separator:a3305941fa615f7134526b718917716ee"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:a3305941fa615f7134526b718917716ee"><td class="memSeparator" colspan="2">&#160;</td></tr>
<tr class="memitem:acbe6549b55d50541d09a16f770e65afc"><td class="memItemLeft" align="right" valign="top">br_ssl_session_parameters *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html#acbe6549b55d50541d09a16f770e65afc">to_br_session</a> ()</td></tr> <tr class="memitem:acbe6549b55d50541d09a16f770e65afc"><td class="memItemLeft" align="right" valign="top">br_ssl_session_parameters *&#160;</td><td class="memItemRight" valign="bottom"><a class="el" href="class_s_s_l_session.html#acbe6549b55d50541d09a16f770e65afc">to_br_session</a> ()</td></tr>
<tr class="memdesc:acbe6549b55d50541d09a16f770e65afc"><td class="mdescLeft">&#160;</td><td class="mdescRight">returns a pointer to the ::br_ssl_session_parameters component of this class <a href="#acbe6549b55d50541d09a16f770e65afc">More...</a><br /></td></tr> <tr class="memdesc:acbe6549b55d50541d09a16f770e65afc"><td class="mdescLeft">&#160;</td><td class="mdescRight">Returns a pointer to the ::br_ssl_session_parameters component of this class. <a href="#acbe6549b55d50541d09a16f770e65afc">More...</a><br /></td></tr>
<tr class="separator:acbe6549b55d50541d09a16f770e65afc"><td class="memSeparator" colspan="2">&#160;</td></tr> <tr class="separator:acbe6549b55d50541d09a16f770e65afc"><td class="memSeparator" colspan="2">&#160;</td></tr>
</table> </table>
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2> <a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<div class="textblock"><p>This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions. </p> <div class="textblock"><p>This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions. </p>
<p><a class="el" href="_s_s_l_session_8h.html">SSLSession.h</a></p> <p><a class="el" href="_s_s_l_session_8h.html">SSLSession.h</a></p>
<p>This file contains a simple utility class to store parameters about an SSL Session for reuse later.This class was created to extend the values stored in br_ssl_session_parameters, which allow BearSSL to resume an SSL session. When testing BearSSL's session resumption feature, it was observed that BearSSL can only resume a session that was was started with the same server. This becomes an issue when using repeated requests to a domain name which can resolve to multiple IP addresses ("api.github.com"), as the device will switch between two or three servers. Since BearSSL only stores one session at a time, this results in session resumption being few and far between.</p> <p>This file contains a simple utility class to store parameters about an SSL Session for reuse later.This class was created to extend the values stored in br_ssl_session_parameters, which allow BearSSL to resume an SSL session. When testing BearSSL's session resumption feature, it was observed that BearSSL can only resume a session that was was started with the same server. This becomes an issue when using repeated requests to a domain name which can resolve to multiple IP addresses ("api.github.com"), as the device will switch between two or three servers. Since BearSSL only stores one session at a time, this results in session resumption being few and far between.</p>
<p>To remedy this problem, an <a class="el" href="class_s_s_l_session.html" title="This class stores values which allow SSLClient to save and resume SSL sessions.">SSLSession</a> stores the IPAddress and hostname, along with the parameters in br_ssl_session_parameters struct. Using this data, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> is able to remember which IPAddress is associated with which session, allowing it to reconnect to the last IPAddress, as opposed to any associated with the domain. </p> <p>To remedy this problem, an <a class="el" href="class_s_s_l_session.html" title="This class stores values which allow SSLClient to save and resume SSL sessions.">SSLSession</a> stores the IPAddress and hostname, along with the parameters in br_ssl_session_parameters struct. Using this data, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is able to remember which IPAddress is associated with which session, allowing it to reconnect to the last IPAddress, as opposed to any associated with the domain. </p>
</div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2> </div><h2 class="groupheader">Constructor &amp; Destructor Documentation</h2>
<a id="ae05648200cea66577f024d5d09a6fcbb"></a> <a id="ae05648200cea66577f024d5d09a6fcbb"></a>
<h2 class="memtitle"><span class="permalink"><a href="#ae05648200cea66577f024d5d09a6fcbb">&#9670;&nbsp;</a></span>SSLSession()</h2> <h2 class="memtitle"><span class="permalink"><a href="#ae05648200cea66577f024d5d09a6fcbb">&#9670;&nbsp;</a></span>SSLSession()</h2>
@ -182,7 +182,8 @@ Public Member Functions</h2></td></tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>delete the parameters and invalidate the session Roughly equivalent to this_session = <a class="el" href="class_s_s_l_session.html#ae05648200cea66577f024d5d09a6fcbb" title="SSLSession constructor.">SSLSession()</a>, however this function preserves the String object, allowing it to better handle the dynamic memory needed. </p> <p>Delete the parameters and invalidate the session. </p>
<p>Roughly equivalent to this_session = <a class="el" href="class_s_s_l_session.html#ae05648200cea66577f024d5d09a6fcbb" title="SSLSession constructor.">SSLSession()</a>, however this function preserves the String object, allowing it to better handle the dynamic memory needed. </p>
</div> </div>
</div> </div>
@ -211,7 +212,7 @@ Public Member Functions</h2></td></tr>
<p>Get the hostname string associated with this session. </p> <p>Get the hostname string associated with this session. </p>
<dl class="section return"><dt>Returns</dt><dd>A String object or "" if there is no hostname </dd></dl> <dl class="section return"><dt>Returns</dt><dd>A String object or "" if there is no hostname </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>must check isValidSession before getting this value, as if this session in invalid this value is not guarented to be reset to "". </dd></dl> <dl class="section pre"><dt>Precondition</dt><dd>must check isValidSession before getting this value, as if this session in invalid this value is not guarenteed to be reset to "". </dd></dl>
</div> </div>
</div> </div>
@ -240,7 +241,7 @@ Public Member Functions</h2></td></tr>
<p>Get ::IPAddress associated with this session. </p> <p>Get ::IPAddress associated with this session. </p>
<dl class="section return"><dt>Returns</dt><dd>A ::IPAddress object, #INADDR_NONE if there is no IP </dd></dl> <dl class="section return"><dt>Returns</dt><dd>A ::IPAddress object, #INADDR_NONE if there is no IP </dd></dl>
<dl class="section pre"><dt>Precondition</dt><dd>must check isValidSession before getting this value, as if this session in invalid this value is not guarented to be reset to #INADDR_NONE. </dd></dl> <dl class="section pre"><dt>Precondition</dt><dd>must check isValidSession before getting this value, as if this session in invalid this value is not guarenteed to be reset to #INADDR_NONE. </dd></dl>
</div> </div>
</div> </div>
@ -325,7 +326,7 @@ Public Member Functions</h2></td></tr>
<p>Set the ip address and hostname of the session. </p> <p>Set the ip address and hostname of the session. </p>
<p>This function stores the ip Address object and hostname object into the session object. If hostname is not null or ip address is not blank, and the ::br_ssl_session_parameters values are non-zero it then validates the session.</p> <p>This function stores the ip Address object and hostname object into the session object. If hostname is not null or ip address is not blank, and the ::br_ssl_session_parameters values are non-zero it then validates the session.</p>
<dl class="section pre"><dt>Precondition</dt><dd>You must call ::br_ssl_engine_get_session_parameters with this session before calling this function. This is because there is no way to completly validate the ::br_ssl_session_parameters and the session may end up in a corrupted state if this is not observed.</dd></dl> <dl class="section pre"><dt>Precondition</dt><dd>You must call ::br_ssl_engine_get_session_parameters with this session before calling this function. This is because there is no way to completely validate the ::br_ssl_session_parameters and the session may end up in a corrupted state if this is not observed.</dd></dl>
<dl class="params"><dt>Parameters</dt><dd> <dl class="params"><dt>Parameters</dt><dd>
<table class="params"> <table class="params">
<tr><td class="paramname">ip</td><td>The IP address of the host associated with the session </td></tr> <tr><td class="paramname">ip</td><td>The IP address of the host associated with the session </td></tr>
@ -359,7 +360,7 @@ Public Member Functions</h2></td></tr>
</table> </table>
</div><div class="memdoc"> </div><div class="memdoc">
<p>returns a pointer to the ::br_ssl_session_parameters component of this class </p> <p>Returns a pointer to the ::br_ssl_session_parameters component of this class. </p>
</div> </div>
</div> </div>

145
docs/html/functions_vars.html Normal file
View file

@ -0,0 +1,145 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>SSLClient: Class Members - Variables</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(initResizable);
/* @license-end */</script>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/searchdata.js"></script>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td id="projectalign" style="padding-left: 0.5em;">
<div id="projectname">SSLClient
&#160;<span id="projectnumber">1.0</span>
</div>
<div id="projectbrief">Add TLS 1.2 functionality to any network library.</div>
</td>
</tr>
</tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.15 -->
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
var searchBox = new SearchBox("searchBox", "search",false,'Search');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
<script type="text/javascript" src="menu.js"></script>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(function() {
initMenu('',true,false,'search.php','Search');
$(document).ready(function() { init_search(); });
});
/* @license-end */</script>
<div id="main-nav"></div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
<div id="nav-tree">
<div id="nav-tree-contents">
<div id="nav-sync" class="sync"></div>
</div>
</div>
<div id="splitbar" style="-moz-user-select:none;"
class="ui-resizable-handle">
</div>
</div>
<script type="text/javascript">
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
$(document).ready(function(){initNavTree('functions_vars.html','');});
/* @license-end */
</script>
<div id="doc-content">
<!-- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
</div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="javascript:void(0)" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<div class="contents">
&#160;<ul>
<li>m_analog_pin
: <a class="el" href="class_s_s_l_client_impl.html#a9fd03216e71ec0d250b3ed2874f08350">SSLClientImpl</a>
</li>
<li>m_client
: <a class="el" href="class_s_s_l_client.html#a3fa6f4acf8149d76dd4fa443df4a2202">SSLClient&lt; C, SessionCache &gt;</a>
</li>
<li>m_debug
: <a class="el" href="class_s_s_l_client_impl.html#a918195d260b3399056bd0477e5249321">SSLClientImpl</a>
</li>
<li>m_hostname
: <a class="el" href="class_s_s_l_session.html#ab5611a1eb7633019a9bfaa7cc86a1645">SSLSession</a>
</li>
<li>m_iobuf
: <a class="el" href="class_s_s_l_client_impl.html#a6b8064ac811810e00b339f15fbe522c3">SSLClientImpl</a>
</li>
<li>m_ip
: <a class="el" href="class_s_s_l_session.html#ab080fda0553cff3be60ef134b68ad029">SSLSession</a>
</li>
<li>m_session_index
: <a class="el" href="class_s_s_l_client_impl.html#a7cc5de19274e5ec689017cbb84aa008a">SSLClientImpl</a>
</li>
<li>m_sessions
: <a class="el" href="class_s_s_l_client.html#a680fa57f70d2f3164dd4b117bba8f001">SSLClient&lt; C, SessionCache &gt;</a>
</li>
<li>m_sslctx
: <a class="el" href="class_s_s_l_client_impl.html#ab6e5219b2edeb01bd949fbb51749adee">SSLClientImpl</a>
</li>
<li>m_trust_anchors
: <a class="el" href="class_s_s_l_client_impl.html#ac84af4c6b35f59642b6814c52cfde5db">SSLClientImpl</a>
</li>
<li>m_trust_anchors_num
: <a class="el" href="class_s_s_l_client_impl.html#a4b86754cee9e04742728ca14e1b0db7f">SSLClientImpl</a>
</li>
<li>m_valid_session
: <a class="el" href="class_s_s_l_session.html#abfe44b78c7c7d0f83919d6031d1d1857">SSLSession</a>
</li>
<li>m_write_idx
: <a class="el" href="class_s_s_l_client_impl.html#a4bdc048774d8be220da7175e1369513f">SSLClientImpl</a>
</li>
<li>m_x509ctx
: <a class="el" href="class_s_s_l_client_impl.html#a942c7bd3ebbb03db249096c8bb591b8c">SSLClientImpl</a>
</li>
</ul>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
<ul>
<li class="footer">Generated by
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.15 </li>
</ul>
</div>
</body>
</html>

6
docs/html/hierarchy.html
View file

@ -94,10 +94,10 @@ $(document).ready(function(){initNavTree('hierarchy.html','');});
<div class="textblock">This inheritance list is sorted roughly, but not completely, alphabetically:</div><div class="directory"> <div class="textblock">This inheritance list is sorted roughly, but not completely, alphabetically:</div><div class="directory">
<div class="levels">[detail level <span onclick="javascript:toggleLevel(1);">1</span><span onclick="javascript:toggleLevel(2);">2</span><span onclick="javascript:toggleLevel(3);">3</span>]</div><table class="directory"> <div class="levels">[detail level <span onclick="javascript:toggleLevel(1);">1</span><span onclick="javascript:toggleLevel(2);">2</span><span onclick="javascript:toggleLevel(3);">3</span>]</div><table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:0px;display:inline-block;">&#160;</span><span id="arr_0_" class="arrow" onclick="toggleFolder('0_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><b>br_ssl_session_parameters</b></td><td class="desc"></td></tr> <tr id="row_0_" class="even"><td class="entry"><span style="width:0px;display:inline-block;">&#160;</span><span id="arr_0_" class="arrow" onclick="toggleFolder('0_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><b>br_ssl_session_parameters</b></td><td class="desc"></td></tr>
<tr id="row_0_0_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_session.html" target="_self">SSLSession</a></td><td class="desc">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions </td></tr> <tr id="row_0_0_"><td class="entry"><span style="width:32px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_session.html" target="_self">SSLSession</a></td><td class="desc">This class stores values which allow <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to save and resume SSL sessions </td></tr>
<tr id="row_1_" class="even"><td class="entry"><span style="width:0px;display:inline-block;">&#160;</span><span id="arr_1_" class="arrow" onclick="toggleFolder('1_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><b>Client</b></td><td class="desc"></td></tr> <tr id="row_1_" class="even"><td class="entry"><span style="width:0px;display:inline-block;">&#160;</span><span id="arr_1_" class="arrow" onclick="toggleFolder('1_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><b>Client</b></td><td class="desc"></td></tr>
<tr id="row_1_0_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_1_0_" class="arrow" onclick="toggleFolder('1_0_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client_impl.html" target="_self">SSLClientImpl</a></td><td class="desc">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> </td></tr> <tr id="row_1_0_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><span id="arr_1_0_" class="arrow" onclick="toggleFolder('1_0_')">&#9660;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client_impl.html" target="_self">SSLClientImpl</a></td><td class="desc">Implementation code to be inherited by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> </td></tr>
<tr id="row_1_0_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client.html" target="_self">SSLClient&lt; C, SessionCache &gt;</a></td><td class="desc">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> class Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info </td></tr> <tr id="row_1_0_0_" class="even"><td class="entry"><span style="width:48px;display:inline-block;">&#160;</span><span class="icona"><span class="icon">C</span></span><a class="el" href="class_s_s_l_client.html" target="_self">SSLClient&lt; C, SessionCache &gt;</a></td><td class="desc">The main <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> class. Check out <a class="el" href="_r_e_a_d_m_e_8md.html">README.md</a> for more info </td></tr>
</table> </table>
</div><!-- directory --> </div><!-- directory -->
</div><!-- contents --> </div><!-- contents -->

69
docs/html/index.html
View file

@ -5,7 +5,7 @@
<meta http-equiv="X-UA-Compatible" content="IE=9"/> <meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.15"/> <meta name="generator" content="Doxygen 1.8.15"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/> <meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>SSLClient: Main Page</title> <title>SSLClient: SSLClient - Arduino Library For SSL</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/> <link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script> <script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script> <script type="text/javascript" src="dynsections.js"></script>
@ -86,11 +86,74 @@ $(document).ready(function(){initNavTree('index.html','');});
</iframe> </iframe>
</div> </div>
<div class="header"> <div class="PageDoc"><div class="header">
<div class="headertitle"> <div class="headertitle">
<div class="title">SSLClient Documentation</div> </div> <div class="title"><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> - Arduino Library For SSL </div> </div>
</div><!--header--> </div><!--header-->
<div class="contents"> <div class="contents">
<div class="textblock"><p><b><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> requires at least 110kb flash and 8kb RAM, and will not compile otherwise. This means that most Arduino boards are not supported. Check your board's specifications before attempting to use this library.</b></p>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is a simple library to add <a href="https://www.websecurity.symantec.com/security-topics/what-is-ssl-tls-https">TLS 1.2</a> functionality to any network library implementing the <a href="https://www.arduino.cc/en/Reference/ClientConstructor">Arduino Client interface</a>, including the Arduino <a href="https://www.arduino.cc/en/Reference/EthernetClient">EthernetClient</a> and <a href="https://www.arduino.cc/en/Reference/WiFiClient">WiFiClient</a> classes (though it is better to prefer WiFClient.connectSSL if implemented). In other words, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> implements encrypted communication through SSL on devices that do not otherwise support it.</p>
<h2>Overview</h2>
<p>Using <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> should be similar to using any other Arduino-based Client class, since this library was developed around compatibility with <a href="https://www.arduino.cc/en/Reference/EthernetClient">EthernetClient</a>. There are a few extra things, however, that you will need to get started:</p>
<ol type="1">
<li>A board with a lot of resources (&gt;110kb flash and &gt;8kb RAM), and a network peripheral with a large internal buffer (&gt;8kb). This library was tested with the <a href="https://www.adafruit.com/product/2772">Adafruit Feather M0</a> (256K flash, 32K RAM) and the <a href="https://www.adafruit.com/product/3201">Adafruit Ethernet Featherwing</a> (16kb Buffer), and we still had to modify the Arduino Ethernet library to support larger internal buffers per socket (see the <a href="#Implementation-Notes">Implementation Notes</a>).</li>
<li>A header containing array of trust anchors, which will look like <a href="./readme/cert.h">this file</a>. These are used to verify the SSL connection later on, and without them you will be unable to use this library. Check out <a class="el" href="_trust_anchors_8md.html">this document</a> on how to generate this file for your project, and for more information about what a trust anchor is.</li>
<li>A Client class associated with a network interface. We tested this library using <a href="https://www.arduino.cc/en/Reference/EthernetClient">EthernetClient</a>, however in theory it will work for any class implementing Client.</li>
<li>An analog pin, used for generating random data at the start of the connection (see the <a href="#Implementation-Notes">Implementation Notes</a>).</li>
</ol>
<p>Once all those are ready, you can create a simple <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> object like this: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;BaseClientType&gt; client(BaseClientInstance, TAs, (size_t)TAs_NUM, AnalogPin);</div></div><!-- fragment --><p> Where:</p><ul>
<li>BaseClientType - The type of BaseClientInstance</li>
<li>BaseClientInstance - An instance of the class you are using for <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> (the class associated with the network interface, from step 3)</li>
<li>TAs - The name of the trust anchor array created in step 2. If you generated a header using the tutorial this will probably be <code>TAs</code>.</li>
<li>TAs_NUM - The number of trust anchors in TAs. If you generated a header using the tutorial this will probably be <code>TAs_NUM</code>.</li>
<li><p class="startli">AnalogPin - The analog pin to pull random data from (step 4).</p>
<p class="startli">For example, if I am using EthernetClient, a generated array of 2 trust anchors, and the analog pin A7, I would declare an <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> instance using: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;EthernetClient&gt; client(EthernetClient(), TAs, 2, A7);</div></div><!-- fragment --><p> Once that is setup, simply use <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> as you would the base client class: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect(&quot;www.arduino.cc&quot;, 443);</div><div class="line">// Make a HTTP request</div><div class="line">client.println(&quot;GET /asciilogo.txt HTTP/1.1&quot;);</div><div class="line">client.println(&quot;User-Agent: AdafruitFeatherM0WiFi&quot;);</div><div class="line">client.print(&quot;Host: &quot;);</div><div class="line">client.println(server);</div><div class="line">client.println(&quot;Connection: close&quot;);</div><div class="line">client.println();</div><div class="line">client.flush();</div><div class="line">// read and print the data</div><div class="line">...</div></div><!-- fragment --><p> <b>Note</b>: <code>client.connect("www.arduino.cc", 443)</code> can take 5-15 seconds to finish. This an unavoidable consequence of the SSL protocol, and is detailed in <a href="#Implementation-Notes">Implementation Notes</a>.</p>
</li>
</ul>
<p>For more information on <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>, check out the <a href="./examples">examples</a>, <a href="./docs/index.html">API documentation</a>, or the rest of this README.</p>
<h2>How It Works</h2>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> was created to integrate SSL seamlessly with the Arduino infrastructure, and so it does just that: implementing the brilliant <a href="https://bearssl.org/">BearSSL</a> as a proxy in front of any Arduino socket library. BearSSL is designed with low flash footprint in mind, and as a result does little verification of improper programming, relying on the developer to ensure the code is correct. Since <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is built specifically for the Arduino ecosystem, most of the code adds those programming checks back in, making debugging a fast and simple process. The rest manages the state of BearSSL, and ensures a manageable memory footprint.</p>
<p>Additionally, the bulk of <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is split into two components: a template class <a href="./src/SSLClient.h">SSLClient</a>, and an implementation class <a href="./src/SSLClientImpl.h">SSLClientImpl</a>. The template class serves to abstract some functions not implemented in the Arduino Client interface (such as EthernetClient::remoteIP), and the implementation class is the rest of the <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> library.</p>
<h2>Other Features</h2>
<h3>Logging</h3>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> also allows for changing the debugging level by adding an additional parameter to the constructor: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;EthernetClient&gt; client(EthernetClient(), TAs, (size_t)2, A7, SSL_INFO);</div></div><!-- fragment --><p> Logging is always outputted through the <a href="https://www.arduino.cc/reference/en/language/functions/communication/serial/">Arduino Serial interface</a>, so you'll need to setup Serial before you can view the SSL logs. Log levels are enumerated in <a class="el" href="_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395" title="Level of verbosity used in logging for SSLClient.">DebugLevel</a>. The log level is set to <code>SSL_WARN</code> by default.</p>
<h3>Errors</h3>
<p>When <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> encounters an error, it will attempt to terminate the SSL session gracefully if possible, and then close the socket. Simple error information can be found from SSLClient::getWriteError(), which will return a value from the <a class="el" href="_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5" title="Static constants defining the possible errors encountered.">Error</a> enum. For more detailed diagnostics, you can look at the serial logs, which will be displayed if the log level is at <code>SSL_ERROR</code> or lower.</p>
<h3>Write Buffering</h3>
<p>As you may have noticed in the documentation for <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a>, calling this function does not actually write to the network. Instead, you must call <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a> or <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will detect that the buffer is ready and write to the network (see <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> for details).</p>
<p>This was implemented as a buffered function because examples in Arduino libraries will often write to the network like so: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">EthernetClient client;</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect(&quot;www.arduino.cc&quot;, 443);</div><div class="line">// ...</div><div class="line">// write an http request to the network</div><div class="line">client.write(&quot;GET /asciilogo.txt HTTP/1.1\r\n&quot;);</div><div class="line">client.write(&quot;Host: arduino.cc\r\n&quot;);</div><div class="line">client.write(&quot;Connection: close\r\n&quot;);</div><div class="line">// wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p> Notice that every single write() call immediately writes to the network, which is fine with most network clients. With SSL, however, if we are encrypting and writing to the network every write() call, this will result in a lot of small encryption tasks. Encryption takes a lot of time and code, so to reduce the overhead of an SSL connection, <a class="el" href="class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270">SSLClient::write</a> implicitly buffers until the developer states that they are waiting for data to be received with <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>. A simple example can be found below:</p>
<div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;EthernetClient&gt; client(EthernetClient(), TAs, 2, A7);</div><div class="line">// ...</div><div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div><div class="line">client.connect(&quot;www.arduino.cc&quot;, 443);</div><div class="line">// ...</div><div class="line">// add http request to the buffer</div><div class="line">client.write(&quot;GET /asciilogo.txt HTTP/1.1\r\n&quot;);</div><div class="line">client.write(&quot;Host: arduino.cc\r\n&quot;);</div><div class="line">client.write(&quot;Connection: close\r\n&quot;);</div><div class="line">// write the bytes to the network, then wait for response</div><div class="line">while (!client.available()) { /* ... */ }</div><div class="line">// ...</div></div><!-- fragment --><p>If you would like to trigger a network write manually without using the <a class="el" href="class_s_s_l_client.html#a40ec85568d0aec376219125b604dbc29" title="Returns the number of bytes available to read from the data that has been received and decrypted.">SSLClient::available</a>, you can also call <a class="el" href="class_s_s_l_client.html#a51eb668f6a328a6a66298c6bc1361d41" title="Force writing the buffered bytes from SSLClient::write to the network.">SSLClient::flush</a>, which will write all data and return when finished.</p>
<h3>Session Caching</h3>
<p>As detailed in the <a href="#resources">resources section</a>, SSL handshakes take an extended period (1-4sec) to negotiate. To remedy this problem, BearSSL is able to keep a <a href="https://bearssl.org/api1.html#session-cache">SSL session cache</a> of the clients it has connected to. If BearSSL successfully resumes an SSL session, it can reduce connection time to 100-500ms.</p>
<p>In order to use SSL session resumption:</p><ul>
<li>The website you are connecting to must support it. Support is widespread, but you can verify easily using the <a href="https://www.ssllabs.com/ssltest/">SSLLabs tool</a>.</li>
<li>You must reuse the same <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> object (SSL Sessions are stored in the object itself).</li>
<li>You must reconnect to the exact same server.</li>
</ul>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> automatically stores an IP address and hostname in each session, ensuring that if you call <code>connect("www.google.com")</code> <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> will use a IP address that recognizes the SSL session instead of another IP address associated with <code>"www.google.com"</code>. However, because some websites have multiple servers on a single IP address (github.com being an example), you may find that even if you are connecting to the same host the connection does not resume. This is a flaw in the SSL session protocol — though it has been resolved in TLS 1.3, the lack of widespread adoption of the new protocol prevents it from being used here. SSL sessions can also expire based on server criteria, which will result in a standard 4-10 second connection.</p>
<p>You can test whether or not a website can resume SSL Sessions using the <a href="./examples/Session_Example/Session_Example.ino">Session Example</a> included with this library. Because of all the confounding factors of SSL Sessions, it is generally prudent while programming to assume the session will always fail to resume.</p>
<p>SSL sessions take a lot of memory to store, so by default <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> will only store one at a time. You can change this behavior by adding the following to your <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> declaration: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;EthernetClient, SomeNumber&gt; client(EthernetClient(), TAs, 2, A7);</div></div><!-- fragment --><p> Where <code>SomeNumber</code> is the number of sessions you would like to store. For example this declaration can store 3 sessions: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">SSLClient&lt;EthernetClient, 3&gt; client(EthernetClient(), TAs, 2, A7);</div></div><!-- fragment --><p> Sessions are managed internally using the SSLSession::getSession function. This function will cycle through sessions in a rotating order, allowing the session cache to continually overwrite old sessions. In general, it is a good idea to use a SessionCache size equal to the number of domains you plan on connecting to.</p>
<p>If you need to clear a session, you can do so using the SSLSession::removeSession function.</p>
<h2>Implementation Gotchas</h2>
<p>Some ideas that didn't quite fit in the API documentation.</p>
<h3>Certificate Verification</h3>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> uses BearSSL's <a href="https://bearssl.org/x509.html#the-minimal-engine">minimal x509 verification engine</a> to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. Check out <a class="el" href="_trust_anchors_8md.html">this document</a> for more details on this component of <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a>.</p>
<p>BearSSL also features a <a href="https://bearssl.org/x509.html#the-known-key-engine">known certificate validation engine</a>, which only allows for a single domain in exchange for a significantly reduced resource usage (flash and CPU time). This functionality is planned to be implemented in the future.</p>
<h3>Resources</h3>
<p>The SSL protocol recommends a device support many different encryption algorithms, as well as protocols for SSL itself. The complexity of both of those components results in many medium sized components forming an extremely large whole. Additionally, most embedded processors lack the sophisticated math hardware commonly found in a modern CPU, and as a result require more instructions to create the encryption algorithms SSL requires. This not only increases size but makes the algorithms slow and memory intensive.</p>
<p>To illustrate this, I will run some tests on various domains below. I haven't yet, but I will.</p>
<p>If flash footprint is becoming a problem, there are numerous debugging strings (~3kb estimated) that can be removed from <code><a class="el" href="_s_s_l_client_8h.html">SSLClient.h</a></code>, <code><a class="el" href="_s_s_l_client_impl_8h.html">SSLClientImpl.h</a></code>, and <code><a class="el" href="_s_s_l_client_impl_8cpp.html">SSLClientImpl.cpp</a></code>. I have not figured out a way to configure compilation of these strings, so you will need to modify the library to remove them yourself.</p>
<h3>Read Buffer Overflow</h3>
<p>SSL is a buffered protocol, and since most microcontrollers have limited resources (see <a href="#resources">Resources</a>), <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> is limited in the size of its buffers. A common problem I encountered with SSL connections is buffer overflow, caused by the server sending too much data at once. This problem is caused by the microcontroller being unable to copy and decrypt data faster than it is being received, forcing some data to be discarded. This usually puts BearSSL in an unrecoverable state, forcing <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to close the connection with a write error. If you are experiencing frequent timeout problems, this could be the reason why.</p>
<p>In order to remedy this problem, the device must be able to read the data faster than it is being received, or alternatively have a cache large enough to store the entire payload. Since SSL's encryption forces the device to read slowly, this means we must increase the cache size. Depending on your platform, there are a number of ways this can be done:</p><ul>
<li>Sometimes your communication shield will have an internal buffer, which can be expanded through the driver code. This is the case with the Arduino Ethernet library (in the form of the MAX_SOCK_NUM and ETHERNET_LARGE_BUFFERS macros), however the library must be modified for the change to take effect.</li>
<li><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> has an internal buffer SSLClientImpl::m_iobuf, which can be expanded. BearSSL limits the amount of data that can be processed based on the stage in the SSL handshake, and so this will change will have limited usefulness.</li>
<li>In some cases, a website will send so much data that even with the above solutions, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> will be unable to keep up (a website with a lot of HTML is an example). In these cases you will have to find another method of retrieving the data you need.</li>
<li>If none of the above are viable, it is possible to implement your own Client class which has an internal buffer much larger than both the driver and BearSSL. This would require in-depth knowledge of programming and the communication shield you are working with, as well as a microcontroller with a significant amount of RAM.</li>
</ul>
<h3>Cipher Support</h3>
<p>By default, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> supports only TLS1.2 and the ciphers listed in <a href="./src/TLS12_only_profile.c">this file</a> under <code>suites[]</code>, and the list is relatively small to keep the connection secure and the flash footprint down. These ciphers should work for most applications, however if for some reason you would like to use an older version of TLS or a different cipher, you can change the BearSSL profile being used by <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> to an <a href="./src/bearssl/src/ssl">alternate one with support for older protocols</a>. To do this, edit <code><a class="el" href="class_s_s_l_client_impl.html#a2b0b9043c8252871272bf6ba199ab67b">SSLClientImpl::SSLClientImpl</a></code> to change these lines: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">br_client_init_TLS12_only(&amp;m_sslctx, &amp;m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div><div class="line">// comment the above line and uncomment the line below if you&#39;re having trouble connecting over SSL</div><div class="line">// br_ssl_client_init_full(&amp;m_sslctx, &amp;m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div></div><!-- fragment --><p> to this: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">// br_client_init_TLS12_only(&amp;m_sslctx, &amp;m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div><div class="line">// comment the above line and uncomment the line below if you&#39;re having trouble connecting over SSL</div><div class="line">br_ssl_client_init_full(&amp;m_sslctx, &amp;m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div></div><!-- fragment --><p> If for some unfortunate reason you need SSL 3.0 or SSL 2.0, you will need to modify the BearSSL profile to enable support. Check out the <a href="https://bearssl.org/api1.html#profiles">BearSSL profiles documentation</a> and I wish you the best of luck. </p>
</div></div><!-- PageDoc -->
</div><!-- contents --> </div><!-- contents -->
</div><!-- doc-content --> </div><!-- doc-content -->
<!-- start footer part --> <!-- start footer part -->

8
docs/html/md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html
View file

@ -91,11 +91,11 @@ $(document).ready(function(){initNavTree('md__c_1__users__noah__documents__ardui
<div class="title">Trust Anchors </div> </div> <div class="title">Trust Anchors </div> </div>
</div><!--header--> </div><!--header-->
<div class="contents"> <div class="contents">
<div class="textblock"><p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> uses BearSSL's <a href="https://bearssl.org/x509.html#the-minimal-engine">minimal x509 verification engine</a> to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. In short, these trust anchor arrays allow BearSSL to verify that the server being connected to is who they say they are, and not someone malicious. You can read more about certificates and why they are important <a href="https://www.globalsign.com/en/ssl-information-center/what-is-an-ssl-certificate/">here</a>.</p> <div class="textblock"><p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> uses BearSSL's <a href="https://bearssl.org/x509.html#the-minimal-engine">minimal x509 verification engine</a> to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. In short, these trust anchor arrays allow BearSSL to verify that the server being connected to is who they say they are, and not someone malicious. You can read more about certificates and why they are important <a href="https://www.globalsign.com/en/ssl-information-center/what-is-an-ssl-certificate/">here</a>.</p>
<p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> stores trust anchors in hardcoded constant variables, passed into <code><a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0" title="Initialize SSLClient with all of the prerequisites needed.">SSLClient::SSLClient</a></code> during setup. These constants are generally stored in their own header file as found in <a href="https://bearssl.org/api1.html#profiles">the BearSSL docs</a>. This header file will look something like: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">#define TAs_NUM 1</div><div class="line"></div><div class="line">static const unsigned char TA_DN0[] = {</div><div class="line"> // lots of raw bytes here</div><div class="line"> // ...</div><div class="line">};</div><div class="line"></div><div class="line">static const unsigned char TA_RSA_N0[] = {</div><div class="line"> // lots of raw bytes here</div><div class="line"> //...</div><div class="line">};</div><div class="line"></div><div class="line">static const unsigned char TA_RSA_E0[] = {</div><div class="line"> // 1-3 bytes here</div><div class="line">};</div><div class="line"></div><div class="line">static const br_x509_trust_anchor TAs[] = {</div><div class="line"> {</div><div class="line"> { (unsigned char *)TA_DN0, sizeof TA_DN0 },</div><div class="line"> BR_X509_TA_CA,</div><div class="line"> {</div><div class="line"> BR_KEYTYPE_RSA,</div><div class="line"> { .rsa = {</div><div class="line"> (unsigned char *)TA_RSA_N0, sizeof TA_RSA_N0,</div><div class="line"> (unsigned char *)TA_RSA_E0, sizeof TA_RSA_E0,</div><div class="line"> } }</div><div class="line"> }</div><div class="line"> },</div><div class="line">};</div></div><!-- fragment --><p> A full example of a trust anchor header can be found in <a href="./readme/cert.h">this file</a>. Full documentation for the format of these variables can be found in the <a href="https://bearssl.org/apidoc/structbr__x509__trust__anchor.html">BearSSL documentation for br_x509_trust_anchor</a>.</p> <p><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> stores trust anchors in hardcoded constant variables, passed into <code><a class="el" href="class_s_s_l_client.html#ae9a7509bc8a18f67e286547c19deb3c0" title="Initialize SSLClient with all of the prerequisites needed.">SSLClient::SSLClient</a></code> during setup. These constants are generally stored in their own header file as found in <a href="https://bearssl.org/api1.html#profiles">the BearSSL docs</a>. This header file will look something like: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">#define TAs_NUM 1</div><div class="line"></div><div class="line">static const unsigned char TA_DN0[] = {</div><div class="line"> // lots of raw bytes here</div><div class="line"> // ...</div><div class="line">};</div><div class="line"></div><div class="line">static const unsigned char TA_RSA_N0[] = {</div><div class="line"> // lots of raw bytes here</div><div class="line"> //...</div><div class="line">};</div><div class="line"></div><div class="line">static const unsigned char TA_RSA_E0[] = {</div><div class="line"> // 1-3 bytes here</div><div class="line">};</div><div class="line"></div><div class="line">static const br_x509_trust_anchor TAs[] = {</div><div class="line"> {</div><div class="line"> { (unsigned char *)TA_DN0, sizeof TA_DN0 },</div><div class="line"> BR_X509_TA_CA,</div><div class="line"> {</div><div class="line"> BR_KEYTYPE_RSA,</div><div class="line"> { .rsa = {</div><div class="line"> (unsigned char *)TA_RSA_N0, sizeof TA_RSA_N0,</div><div class="line"> (unsigned char *)TA_RSA_E0, sizeof TA_RSA_E0,</div><div class="line"> } }</div><div class="line"> }</div><div class="line"> },</div><div class="line">};</div></div><!-- fragment --><p> A full example of a trust anchor header can be found in <a href="./readme/cert.h">this file</a>. Full documentation for the format of these variables can be found in the <a href="https://bearssl.org/apidoc/structbr__x509__trust__anchor.html">BearSSL documentation for br_x509_trust_anchor</a>.</p>
<h2>Generating Trust Anchors</h2> <h2>Generating Trust Anchors</h2>
<h3>HTTPS</h3> <h3>HTTPS</h3>
<p>For HTTPS, there a couple of tools you can use. Ordered from easy to hard:</p><ul> <p>For HTTPS, there a couple of tools you can use. Ordered from easiest to hardest:</p><ul>
<li><a href="https://openslab-osu.github.io/bearssl-certificate-utility/">This website, written to simplify the creation of trust anchor headers</a>. Simply plug and play.</li> <li><a href="https://openslab-osu.github.io/bearssl-certificate-utility/">This website, written to simplify the creation of trust anchor headers</a>. Simply plug and play.</li>
<li><a href="./tools/pycert_bearssl/pycert_bearssl.py">pycert_bearssl</a>, a command line utility based on a <a href="https://learn.adafruit.com/introducing-the-adafruit-wiced-feather-wifi/pycert-dot-py">pycert</a>. You will need to install Python 3, and follow the instructions in the <a href="./tools/pycert_bearssl/pycert_bearssl.py">pycert_bearssl.py file</a>. You'll want to use the <code>pycert_bearssl.py download</code> command once the utility is set up.</li> <li><a href="./tools/pycert_bearssl/pycert_bearssl.py">pycert_bearssl</a>, a command line utility based on a <a href="https://learn.adafruit.com/introducing-the-adafruit-wiced-feather-wifi/pycert-dot-py">pycert</a>. You will need to install Python 3, and follow the instructions in the <a href="./tools/pycert_bearssl/pycert_bearssl.py">pycert_bearssl.py file</a>. You'll want to use the <code>pycert_bearssl.py download</code> command once the utility is set up.</li>
<li>The brssl command line utility, included in the <a href="https://bearssl.org/gitweb/?p=BearSSL;a=blob_plain;f=tools/brssl.h;hb=HEAD">BearSSL source</a>. You will need to compile this file yourself.</li> <li>The brssl command line utility, included in the <a href="https://bearssl.org/gitweb/?p=BearSSL;a=blob_plain;f=tools/brssl.h;hb=HEAD">BearSSL source</a>. You will need to compile this file yourself.</li>
@ -103,7 +103,7 @@ $(document).ready(function(){initNavTree('md__c_1__users__noah__documents__ardui
<h3>Other Connections</h3> <h3>Other Connections</h3>
<p>For other kinds of SSL connections, you will need to find the root certificate being used by your host. You can check out <a href="https://superuser.com/questions/97201/how-to-save-a-remote-server-ssl-certificate-locally-as-a-file">this StackExchange post</a> for numerous methods of acquiring this certificate from a server. If these methods are not sufficient, you may need to request this certificate from your network administrator. Once you have the certificate, convert it to PEM format if needed (I use <a href="https://www.sslshopper.com/ssl-converter.html">this website</a>), and use the <code>pycert_bearssl.py convert</code> command to convert the certificate into a trust anchor header.</p> <p>For other kinds of SSL connections, you will need to find the root certificate being used by your host. You can check out <a href="https://superuser.com/questions/97201/how-to-save-a-remote-server-ssl-certificate-locally-as-a-file">this StackExchange post</a> for numerous methods of acquiring this certificate from a server. If these methods are not sufficient, you may need to request this certificate from your network administrator. Once you have the certificate, convert it to PEM format if needed (I use <a href="https://www.sslshopper.com/ssl-converter.html">this website</a>), and use the <code>pycert_bearssl.py convert</code> command to convert the certificate into a trust anchor header.</p>
<h2>Using Trust Anchors</h2> <h2>Using Trust Anchors</h2>
<p>Once you've generated a trust anchor array, add it to your Arduino sketch using the <code>Sketch-&gt;Add File</code> button in the Arduino IDE, and link it to your <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class Check out README.md for more info.">SSLClient</a> like so: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">#include &quot;yourtrustanchorfile.h&quot;</div><div class="line">// ...</div><div class="line">SSLClient&lt;SomeClientType&gt; client(SomeClient, TAs, (size_t)TAs_NUM, SomePin);</div><div class="line">// ...</div></div><!-- fragment --><p> Where <code>yourtrustanchorfile.h</code> contains a generated trust anchor array names <code>TAs</code>, with length <code>TAs_NUM</code>. BearSSL will now automatically use these trust anchors when <code><a class="el" href="class_s_s_l_client.html#ae6540b9a02f1392bf2ac48421189f70e" title="Connect over SSL to a host specified by an IP address.">SSLClient::connect</a></code> is called. </p> <p>Once you've generated a trust anchor array, add it to your Arduino sketch using the <code>Sketch-&gt;Add File</code> button in the Arduino IDE, and link it to your <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> like so: </p><div class="fragment"><div class="line"> {C++}</div><div class="line">#include &quot;yourtrustanchorfile.h&quot;</div><div class="line">// ...</div><div class="line">SSLClient&lt;SomeClientType&gt; client(SomeClient, TAs, (size_t)TAs_NUM, SomePin);</div><div class="line">// ...</div></div><!-- fragment --><p> Where <code>yourtrustanchorfile.h</code> contains a generated trust anchor array names <code>TAs</code>, with length <code>TAs_NUM</code>. BearSSL will now automatically use these trust anchors when <code><a class="el" href="class_s_s_l_client.html#ae6540b9a02f1392bf2ac48421189f70e" title="Connect over SSL to a host specified by an IP address.">SSLClient::connect</a></code> is called. </p>
</div></div><!-- PageDoc --> </div></div><!-- PageDoc -->
</div><!-- contents --> </div><!-- contents -->
</div><!-- doc-content --> </div><!-- doc-content -->

2
docs/html/navtreedata.js
View file

@ -24,7 +24,7 @@ for the JavaScript code in this file
var NAVTREE = var NAVTREE =
[ [
[ "SSLClient", "index.html", [ [ "SSLClient", "index.html", [
[ "SSLClient - Arduino Library For SSL", "md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__r_e_a_d_m_e.html", null ], [ "SSLClient - Arduino Library For SSL", "index.html", null ],
[ "Trust Anchors", "md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html", null ], [ "Trust Anchors", "md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html", null ],
[ "Classes", "annotated.html", [ [ "Classes", "annotated.html", [
[ "Class List", "annotated.html", "annotated_dup" ], [ "Class List", "annotated.html", "annotated_dup" ],

2
docs/html/navtreeindex0.js
View file

@ -108,8 +108,8 @@ var NAVTREEINDEX0 =
"globals_func.html":[3,1,1], "globals_func.html":[3,1,1],
"globals_vars.html":[3,1,2], "globals_vars.html":[3,1,2],
"hierarchy.html":[2,2], "hierarchy.html":[2,2],
"index.html":[0],
"index.html":[], "index.html":[],
"md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__r_e_a_d_m_e.html":[0],
"md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html":[1], "md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html":[1],
"pages.html":[], "pages.html":[],
"time__macros_8h.html":[3,0,1,5], "time__macros_8h.html":[3,0,1,5],

3
docs/html/pages.html
View file

@ -93,8 +93,7 @@ $(document).ready(function(){initNavTree('pages.html','');});
<div class="contents"> <div class="contents">
<div class="textblock">Here is a list of all related documentation pages:</div><div class="directory"> <div class="textblock">Here is a list of all related documentation pages:</div><div class="directory">
<table class="directory"> <table class="directory">
<tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__r_e_a_d_m_e.html" target="_self">SSLClient - Arduino Library For SSL</a></td><td class="desc"></td></tr> <tr id="row_0_" class="even"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html" target="_self">Trust Anchors</a></td><td class="desc"></td></tr>
<tr id="row_1_"><td class="entry"><span style="width:16px;display:inline-block;">&#160;</span><a class="el" href="md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html" target="_self">Trust Anchors</a></td><td class="desc"></td></tr>
</table> </table>
</div><!-- directory --> </div><!-- directory -->
</div><!-- contents --> </div><!-- contents -->

2
docs/html/search/all_e.js
View file

@ -1,6 +1,6 @@
var searchData= var searchData=
[ [
['sslclient_20_2d_20arduino_20library_20for_20ssl',['SSLClient - Arduino Library For SSL',['../md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__r_e_a_d_m_e.html',1,'']]], ['sslclient_20_2d_20arduino_20library_20for_20ssl',['SSLClient - Arduino Library For SSL',['../index.html',1,'']]],
['sec_5fper_5fday',['SEC_PER_DAY',['../time__macros_8h.html#a3aaee30ddedb3f6675aac341a66e39e2',1,'time_macros.h']]], ['sec_5fper_5fday',['SEC_PER_DAY',['../time__macros_8h.html#a3aaee30ddedb3f6675aac341a66e39e2',1,'time_macros.h']]],
['sec_5fper_5fhour',['SEC_PER_HOUR',['../time__macros_8h.html#a2d540510d5860d7f190d13124956bc57',1,'time_macros.h']]], ['sec_5fper_5fhour',['SEC_PER_HOUR',['../time__macros_8h.html#a2d540510d5860d7f190d13124956bc57',1,'time_macros.h']]],
['sec_5fper_5fmin',['SEC_PER_MIN',['../time__macros_8h.html#ac47b302f1b8d2a7a9c035c417247be76',1,'time_macros.h']]], ['sec_5fper_5fmin',['SEC_PER_MIN',['../time__macros_8h.html#ac47b302f1b8d2a7a9c035c417247be76',1,'time_macros.h']]],

2
docs/html/search/pages_0.js
View file

@ -1,4 +1,4 @@
var searchData= var searchData=
[ [
['sslclient_20_2d_20arduino_20library_20for_20ssl',['SSLClient - Arduino Library For SSL',['../md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__r_e_a_d_m_e.html',1,'']]] ['sslclient_20_2d_20arduino_20library_20for_20ssl',['SSLClient - Arduino Library For SSL',['../index.html',1,'']]]
]; ];

30
docs/html/search/variables_1.html Normal file
View file

@ -0,0 +1,30 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html><head><title></title>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta name="generator" content="Doxygen 1.8.15"/>
<link rel="stylesheet" type="text/css" href="search.css"/>
<script type="text/javascript" src="variables_1.js"></script>
<script type="text/javascript" src="search.js"></script>
</head>
<body class="SRPage">
<div id="SRIndex">
<div class="SRStatus" id="Loading">Loading...</div>
<div id="SRResults"></div>
<script type="text/javascript"><!--
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
createResults();
/* @license-end */
--></script>
<div class="SRStatus" id="Searching">Searching...</div>
<div class="SRStatus" id="NoMatches">No Matches</div>
<script type="text/javascript"><!--
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
document.getElementById("Loading").style.display="none";
document.getElementById("NoMatches").style.display="none";
var searchResults = new SearchResults("searchResults");
searchResults.Search();
/* @license-end */
--></script>
</div>
</body>
</html>

17
docs/html/search/variables_1.js Normal file
View file

@ -0,0 +1,17 @@
var searchData=
[
['m_5fanalog_5fpin',['m_analog_pin',['../class_s_s_l_client_impl.html#a9fd03216e71ec0d250b3ed2874f08350',1,'SSLClientImpl']]],
['m_5fclient',['m_client',['../class_s_s_l_client.html#a3fa6f4acf8149d76dd4fa443df4a2202',1,'SSLClient']]],
['m_5fdebug',['m_debug',['../class_s_s_l_client_impl.html#a918195d260b3399056bd0477e5249321',1,'SSLClientImpl']]],
['m_5fhostname',['m_hostname',['../class_s_s_l_session.html#ab5611a1eb7633019a9bfaa7cc86a1645',1,'SSLSession']]],
['m_5fiobuf',['m_iobuf',['../class_s_s_l_client_impl.html#a6b8064ac811810e00b339f15fbe522c3',1,'SSLClientImpl']]],
['m_5fip',['m_ip',['../class_s_s_l_session.html#ab080fda0553cff3be60ef134b68ad029',1,'SSLSession']]],
['m_5fsession_5findex',['m_session_index',['../class_s_s_l_client_impl.html#a7cc5de19274e5ec689017cbb84aa008a',1,'SSLClientImpl']]],
['m_5fsessions',['m_sessions',['../class_s_s_l_client.html#a680fa57f70d2f3164dd4b117bba8f001',1,'SSLClient']]],
['m_5fsslctx',['m_sslctx',['../class_s_s_l_client_impl.html#ab6e5219b2edeb01bd949fbb51749adee',1,'SSLClientImpl']]],
['m_5ftrust_5fanchors',['m_trust_anchors',['../class_s_s_l_client_impl.html#ac84af4c6b35f59642b6814c52cfde5db',1,'SSLClientImpl']]],
['m_5ftrust_5fanchors_5fnum',['m_trust_anchors_num',['../class_s_s_l_client_impl.html#a4b86754cee9e04742728ca14e1b0db7f',1,'SSLClientImpl']]],
['m_5fvalid_5fsession',['m_valid_session',['../class_s_s_l_session.html#abfe44b78c7c7d0f83919d6031d1d1857',1,'SSLSession']]],
['m_5fwrite_5fidx',['m_write_idx',['../class_s_s_l_client_impl.html#a4bdc048774d8be220da7175e1369513f',1,'SSLClientImpl']]],
['m_5fx509ctx',['m_x509ctx',['../class_s_s_l_client_impl.html#a942c7bd3ebbb03db249096c8bb591b8c',1,'SSLClientImpl']]]
];

2
src/SSLClient.h
View file

@ -27,7 +27,7 @@
#define SSLClient_H_ #define SSLClient_H_
/** /**
* @brief The main SSLClient class * @brief The main SSLClient class.
* Check out README.md for more info. * Check out README.md for more info.
*/ */

18
src/SSLClientImpl.h
View file

@ -70,7 +70,7 @@ enum DebugLevel {
/** @brief Implementation code to be inherited by SSLClient */ /** @brief Implementation code to be inherited by SSLClient */
class SSLClientImpl : public Client { class SSLClientImpl : public Client {
public: public:
/** See SSLClient::SSLClient */ /** @see SSLClient::SSLClient */
explicit SSLClientImpl(const br_x509_trust_anchor *trust_anchors, explicit SSLClientImpl(const br_x509_trust_anchor *trust_anchors,
const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug); const size_t trust_anchors_num, const int analog_pin, const DebugLevel debug);
@ -96,28 +96,28 @@ public:
void stop_impl(); void stop_impl();
/** @see SSLClient::connected */ /** @see SSLClient::connected */
uint8_t connected_impl(); uint8_t connected_impl();
/** See SSLClient::getSession */ /** @see SSLClient::getSession */
SSLSession& get_session_impl(const char* host, const IPAddress& addr); SSLSession& get_session_impl(const char* host, const IPAddress& addr);
/** See SSLClient::removeSession */ /** @see SSLClient::removeSession */
void remove_session_impl(const char* host, const IPAddress& addr); void remove_session_impl(const char* host, const IPAddress& addr);
//============================================ //============================================
//= Functions implemented in SSLClient.h //= Functions implemented in SSLClient.h
//============================================ //============================================
/** See SSLClient::localPort */ /** @see SSLClient::localPort */
virtual uint16_t localPort() = 0; virtual uint16_t localPort() = 0;
/** See SSLClient::remoteIP */ /** @see SSLClient::remoteIP */
virtual IPAddress remoteIP() = 0; virtual IPAddress remoteIP() = 0;
/** See SSLClient::localPort */ /** @see SSLClient::localPort */
virtual uint16_t remotePort() = 0; virtual uint16_t remotePort() = 0;
/** See SSLClient::getSessionCount */ /** @see SSLClient::getSessionCount */
virtual size_t getSessionCount() const = 0; virtual size_t getSessionCount() const = 0;
protected: protected:
/** See SSLClient::get_arduino_client */ /** @see SSLClient::get_arduino_client */
virtual Client& get_arduino_client() = 0; virtual Client& get_arduino_client() = 0;
virtual const Client& get_arduino_client() const = 0; virtual const Client& get_arduino_client() const = 0;
/** See SSLClient::get_session_array */ /** @see SSLClient::get_session_array */
virtual SSLSession* get_session_array() = 0; virtual SSLSession* get_session_array() = 0;
virtual const SSLSession* get_session_array() const = 0; virtual const SSLSession* get_session_array() const = 0;