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

Deploying to gh-pages from @ cbb4493876 🚀

Browse source
This commit is contained in:
prototypicalpro 2021-03-21 23:17:23 +00:00
parent 5f730b5f6f
commit 7452a745bf
133 changed files with 819 additions and 712 deletions
Download patch file Download diff file Expand all files Collapse all files

36
index.html
View file

@ -3,7 +3,7 @@
<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.20"/>
<meta name="generator" content="Doxygen 1.9.1"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>SSLClient: SSLClient</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
@ -34,10 +34,10 @@
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.20 -->
<!-- Generated by Doxygen 1.9.1 -->
<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');
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
/* @license-end */
</script>
<script type="text/javascript" src="menudata.js"></script>
@ -101,7 +101,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<p>Once all those are ready, you can create 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> object like this: </p><div class="fragment"><div class="line"> {C++}</div>
<div class="line">BaseClientType baseClientInstance;</div>
<div class="line">SSLClient client(baseClientInstance, TAs, (size_t)TAs_NUM, AnalogPin);</div>
</div><!-- fragment --><p>Where:</p><ul>
</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). It is important that this instance be stored <em>outside</em> 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> declaration (for instance, <code><a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient(BaseClientType() ...)</a></code> wouldn't work).</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>
@ -110,9 +110,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<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">EthernetClient baseClient;</div>
<div class="line">SSLClient client(baseClient, TAs, 2, A7);</div>
</div><!-- fragment --></li>
</ul>
<p>Given this client, 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><!-- fragment --><p> Given this client, 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>
@ -125,14 +123,16 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<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 on some low-power devices. This an unavoidable consequence of the SSL protocol, and is detailed more in <a href="#resources">Implementation Gotchas</a>.</p>
</div><!-- fragment --><p> <b>Note</b>: <code>client.connect("www.arduino.cc", 443)</code> can take 5-15 seconds to finish on some low-power devices. This an unavoidable consequence of the SSL protocol, and is detailed more in <a href="#resources">Implementation Gotchas</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="https://openslab-osu.github.io/SSLClient/html/index.html">API documentation</a>, or the rest of this README.</p>
<h1>Other Features</h1>
<h2>Logging</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> 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">EthernetClient baseClient;</div>
<div class="line">SSLClient client(baseClient, TAs, (size_t)2, A7, 1, SSLClient::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 ::DebugLevel. The log level is set to <code>SSL_WARN</code> by default.</p>
</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 ::DebugLevel. The log level is set to <code>SSL_WARN</code> by default.</p>
<h2>Errors</h2>
<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 ::Error 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>
<h2>Write Buffering</h2>
@ -150,7 +150,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<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#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">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#a0e775669b4a040fbd3f281dcbcd2de78" 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><!-- 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#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">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#a0e775669b4a040fbd3f281dcbcd2de78" 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">EthernetClient baseClient;</div>
<div class="line">SSLClient client(baseClient, TAs, (size_t)2, A7);</div>
@ -178,10 +178,10 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<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">EthernetClient baseClient;</div>
<div class="line">SSLClient client(baseClient, TAs, (size_t)2, A7, SomeNumber);</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><!-- 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">EthernetClient baseClient;</div>
<div class="line">SSLClient client(baseClient, TAs, (size_t)2, A7, 3);</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>
</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>mTLS</h2>
<p>As of <code>v1.6.0</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> supports <a href="https://developers.cloudflare.com/access/service-auth/mtls/">mutual TLS authentication</a>. mTLS is a varient of TLS that verifys both the server and device identities before a connection, and is commonly used in IoT protocols as a secure layer (MQTT over TLS, HTTPS over TLS, etc.).</p>
@ -218,7 +218,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<div class="line"> ...</div>
<div class="line">}</div>
<div class="line">...</div>
</div><!-- fragment --><p>The client certificate must be formatted correctly (according to <a href="https://bearssl.org/apidoc/bearssl__pem_8h.html">BearSSL's specification</a>) in order for mTLS to work. If the certificate is improperly formatted, <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 attempt to make a regular TLS connection instead of an mTLS one, and fail to connect as a result. Because of this, if you are seeing errors similar to <code>"peer did not send certificate chain"</code> on your server, check that your certificate and key are formatted correctly (see <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/7#issuecomment-593704969">https://github.com/OPEnSLab-OSU/SSLClient/issues/7#issuecomment-593704969</a>). 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>'s mTLS functionality, please see the <a href="https://openslab-osu.github.io/SSLClient/class_s_s_l_client_parameters.html">SSLClientParameters documentation</a>.</p>
</div><!-- fragment --><p> The client certificate must be formatted correctly (according to <a href="https://bearssl.org/apidoc/bearssl__pem_8h.html">BearSSL's specification</a>) in order for mTLS to work. If the certificate is improperly formatted, <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 attempt to make a regular TLS connection instead of an mTLS one, and fail to connect as a result. Because of this, if you are seeing errors similar to <code>"peer did not send certificate chain"</code> on your server, check that your certificate and key are formatted correctly (see <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/7#issuecomment-593704969">https://github.com/OPEnSLab-OSU/SSLClient/issues/7#issuecomment-593704969</a>). 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>'s mTLS functionality, please see the <a href="https://openslab-osu.github.io/SSLClient/class_s_s_l_client_parameters.html">SSLClientParameters documentation</a>.</p>
<p>Note that both the above client certificate information <em>as well as</em> the correct trust anchors associated with the server are needed for the connection to succeed. Trust anchors will typically be generated from the CA used to generate the server certificate. More information on generating trust anchors can be found in <a class="el" href="md__trust_anchors.html">TrustAnchors.md</a>.</p>
<h1>Implementation Gotchas</h1>
<p>Some ideas that didn't quite fit in the API documentation.</p>
@ -245,7 +245,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<div class="line">// does not always seem to work in practice (maybe Wiznet bugs?)</div>
<div class="line">//#define ETHERNET_LARGE_BUFFERS</div>
<div class="line">...</div>
</div><!-- fragment --><p>With this: </p><div class="fragment"><div class="line"> {C++}</div>
</div><!-- fragment --><p> With this: </p><div class="fragment"><div class="line"> {C++}</div>
<div class="line">...</div>
<div class="line">// Configure the maximum number of sockets to support. W5100 chips can have</div>
<div class="line">// up to 4 sockets. W5200 &amp; W5500 can have up to 8 sockets. Several bytes</div>
@ -261,7 +261,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<div class="line">// does not always seem to work in practice (maybe Wiznet bugs?)</div>
<div class="line">#define ETHERNET_LARGE_BUFFERS</div>
<div class="line">...</div>
</div><!-- fragment --><p>You may need to use <code>sudo</code> or administrator permissions to make this modification. We change <code>MAX_SOCK_NUM</code> and <code>ETHERNET_LARGE_BUFFERS</code> so the Ethernet hardware can allocate a larger space 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>, however a downside of this modification is we are now only able to have two sockets concurrently. As most microprocessors barely have enough memory for one SSL connection, this limitation will rarely be encountered in practice.</p>
</div><!-- fragment --><p> You may need to use <code>sudo</code> or administrator permissions to make this modification. We change <code>MAX_SOCK_NUM</code> and <code>ETHERNET_LARGE_BUFFERS</code> so the Ethernet hardware can allocate a larger space 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>, however a downside of this modification is we are now only able to have two sockets concurrently. As most microprocessors barely have enough memory for one SSL connection, this limitation will rarely be encountered in practice.</p>
<h2>Seeding Random Data</h2>
<p>The SSL protocol requires that <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> generate some random bits before connecting with a server. BearSSL provides a random number generator but requires a <a href="https://bearssl.org/apidoc/bearssl__ssl_8h.html#a7d8e8de2afd49d6794eae02f56f81152">some entropy for a seed</a>. Normally this seed is generated by taking the microsecond time using the internal clock, however since most microcontrollers are not build with this feature another source must be found. As a simple solution, <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 a floating analog pin as an external source of random data, passed through to the constructor in the <code>analog_pin</code> argument. Before every 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 take the bottom byte from 16 analog reads on <code>analog_pin</code>, and combine these bytes into a 16 byte random number, which is used as a seed for BearSSL. To ensure the most random data, it is recommended that this analog pin be either floating or connected to a location not modifiable by the microcontroller (i.e. a battery voltage readout).</p>
<h2>Certificate Verification</h2>
@ -286,11 +286,11 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<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><!-- 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><!-- 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>
<h2>Security</h2>
<p>Unlike BearSSL, <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 not rigorously vetted to be secure. If your project has security requirements, I recommend you utilize BearSSL directly.</p>
<h2>Known Issues</h2>
@ -307,7 +307,7 @@ $(document).ready(function(){initNavTree('index.html',''); initResizable(); });
<!-- 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.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
<li class="footer">Generated by <a href="https://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.9.1 </li>
</ul>
</div>
</body>