352 lines
45 KiB
HTML
352 lines
45 KiB
HTML
<!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.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"/>
|
|
<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>
|
|
<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
|
|
 <span id="projectnumber">v1.6.11</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.9.1 -->
|
|
<script type="text/javascript">
|
|
/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
|
|
var searchBox = new SearchBox("searchBox", "search",false,'Search','.html');
|
|
/* @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&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&dn=gpl-2.0.txt GPL-v2 */
|
|
$(document).ready(function(){initNavTree('index.html',''); initResizable(); });
|
|
/* @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="PageDoc"><div class="header">
|
|
<div class="headertitle">
|
|
<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> </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><p><a class="anchor" id="md_README"></a> <img src="https://github.com/OPEnSLab-OSU/SSLClient/workflows/CI/badge.svg" alt="CI" style="pointer-events: none;" class="inline"/></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> adds <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. <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 TLS seamlessly with the Arduino infrastructure using <a href="https://bearssl.org/">BearSSL</a> as an underlying TLS engine. Unlike <a href="https://github.com/arduino-libraries/ArduinoBearSSL">ArduinoBearSSL</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 completly self-contained, and does not require any additional hardware (other than a network connection).</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> officially supports SAMD21, SAM3X, ESP32, TIVA C, STM32F7, and Teensy >= 3.0; but it should work on any board with at least 110kB flash and 7kB RAM. SSClient does not currently support ESP8266 (see <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/5#issuecomment-569968546">this issue</a>) or AVR due to memory constraints on both platforms.</p>
|
|
<p>You can also view this README in <a href="https://openslab-osu.github.io/SSLClient/index.html">doxygen</a>.</p>
|
|
<h1>Overview</h1>
|
|
<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> is similar to using any other Arduino-based Client class, as 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><b>Board and Network Peripheral</b> - Your board should have a lot of resources (>110kB flash and >7kB RAM), and your network peripheral should have a large internal buffer (>7kB). 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="#sslclient-with-ethernet">Implementation Gotchas</a>).</li>
|
|
<li><b>Trust Anchors</b> - You will need a header containing array of trust anchors (<a href="./readme/cert.h">example</a>), which are used to verify the SSL connection later on. <b>This file must generated for every project.</b> Check out <a href="./TrustAnchors.md#generating-trust-anchors">TrustAnchors.md</a> on how to generate this file for your project, and for more information about what a trust anchor is.</li>
|
|
<li><b>Network Peripheral Driver Implementing <code>Client</code></b> - Examples include <code>EthernetClient</code>, <code>WiFiClient</code>, and so on—SSLClient will run on top of any network driver exposing the <code>Client</code> interface.</li>
|
|
<li><b>Analog Pin</b> - Used for generating random data at the start of the connection (see the <a href="#implementation-gotchas">Implementation Gotchas</a>).</li>
|
|
</ol>
|
|
<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>
|
|
<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>
|
|
<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">EthernetClient baseClient;</div>
|
|
<div class="line">SSLClient client(baseClient, TAs, 2, A7);</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("www.arduino.cc", 443);</div>
|
|
<div class="line">// Make a HTTP request</div>
|
|
<div class="line">client.println("GET /asciilogo.txt HTTP/1.1");</div>
|
|
<div class="line">client.println("User-Agent: AdafruitFeatherM0WiFi");</div>
|
|
<div class="line">client.print("Host: ");</div>
|
|
<div class="line">client.println(server);</div>
|
|
<div class="line">client.println("Connection: close");</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 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>
|
|
<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>
|
|
<p>As you may have noticed in the documentation for <a class="el" href="class_s_s_l_client.html#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">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#a0e775669b4a040fbd3f281dcbcd2de78" 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#aaf2192a6621fdf2f89cc26a9a1584f8c" 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#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">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("www.arduino.cc", 443);</div>
|
|
<div class="line">// ...</div>
|
|
<div class="line">// write an http request to the network</div>
|
|
<div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div>
|
|
<div class="line">client.write("Host: arduino.cc\r\n");</div>
|
|
<div class="line">client.write("Connection: close\r\n");</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 <code>client.write()</code> call immediately writes to the network. This behavior is fine for most network clients; with SSL, however, it results in many small encryption tasks that consume resources. 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>
|
|
<div class="line">// ...</div>
|
|
<div class="line">// connect to ardiuino.cc over ssl (port 443 for websites)</div>
|
|
<div class="line">client.connect("www.arduino.cc", 443);</div>
|
|
<div class="line">// ...</div>
|
|
<div class="line">// add http request to the buffer</div>
|
|
<div class="line">client.write("GET /asciilogo.txt HTTP/1.1\r\n");</div>
|
|
<div class="line">client.write("Host: arduino.cc\r\n");</div>
|
|
<div class="line">client.write("Connection: close\r\n");</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#a0e775669b4a040fbd3f281dcbcd2de78" 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#aaf2192a6621fdf2f89cc26a9a1584f8c" 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>
|
|
<h2>Session Caching</h2>
|
|
<p>As detailed in the <a href="#resources">resources section</a>, SSL handshakes take an extended period (1-4sec) to negotiate. 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 which can drastically reduce this time: if BearSSL successfully resumes an SSL session, connection time is typically 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, and you can verify it using <a href="https://www.ssllabs.com/ssltest/">SSLLabs</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 (detailed below).</li>
|
|
</ul>
|
|
<blockquote class="doxtable">
|
|
<p>NOTE: <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 the same SSL session for that hostname. Unfortunately some websites have multiple servers on a single IP address (github.com being an example), so you may find that even if you are connecting to the same host the connection will 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 resolved here.</p>
|
|
<p>SSL sessions can also expire based on server criteria (ex. timeout), which will result in a standard 4-10 second connection. </p>
|
|
</blockquote>
|
|
<p>SSL sessions take 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 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>
|
|
<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 verifies both the server and device identities before a connection, and is commonly used in IoT protocols as a secure layer (MQTT over TLS, HTTP over TLS, etc.).</p>
|
|
<p>To use mTLS 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> you will need to a client certificate and client private key associated with the server you are attempting to connect to. Depending on your use case, you will either generate these yourself (ex. <a href="http://www.steves-internet-guide.com/creating-and-using-client-certificates-with-mqtt-and-mosquitto/">Mosquito MQTT setup</a>), or have them generated for you (ex. <a href="https://docs.aws.amazon.com/iot/latest/developerguide/create-device-certificate.html">AWS IoT Certificate Generation</a>). Given this cryptographic information, you can modify the standard <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> connection sketch to enable mTLS authentication: </p><div class="fragment"><div class="line"> {C++}</div>
|
|
<div class="line">...</div>
|
|
<div class="line">/* Somewhere above setup() */</div>
|
|
<div class="line"> </div>
|
|
<div class="line">// The client certificate, can be PEM or DER format</div>
|
|
<div class="line">// DER format will be an array of raw bytes, and PEM format will be a string</div>
|
|
<div class="line">// PEM format is shown below</div>
|
|
<div class="line">const char my_cert[] = </div>
|
|
<div class="line">"-----BEGIN CERTIFICATE-----\n"</div>
|
|
<div class="line">"MIIDpDCCAowCCQC7mCk5Iu3YmDANBgkqhkiG9w0BAQUFADCBkzELMAkGA1UEBhMC\n"</div>
|
|
<div class="line">...</div>
|
|
<div class="line">"-----END CERTIFICATE-----\n";</div>
|
|
<div class="line"> </div>
|
|
<div class="line">// The client private key, must be the same format as the client certificate</div>
|
|
<div class="line">// Both RSA and ECC are supported, ECC is shown below</div>
|
|
<div class="line">const char my_key[] = </div>
|
|
<div class="line">"-----BEGIN EC PRIVATE KEY-----\n"</div>
|
|
<div class="line">...</div>
|
|
<div class="line">"-----END EC PRIVATE KEY-----\n";</div>
|
|
<div class="line"> </div>
|
|
<div class="line">// This line will parse and store the above information so SSLClient can use it later</div>
|
|
<div class="line">// Replace `fromPEM` with `fromDER` if you are using DER formatted certificates.</div>
|
|
<div class="line">SSLClientParameters mTLS = SSLClientParameters::fromPEM(my_cert, sizeof(cert), my_key, sizeof(key));</div>
|
|
<div class="line">SSLClient my_client(...);</div>
|
|
<div class="line">...</div>
|
|
<div class="line">void setup() {</div>
|
|
<div class="line"> ...</div>
|
|
<div class="line"> /* Before SSLClient connects */</div>
|
|
<div class="line"> </div>
|
|
<div class="line"> my_client.setMutualAuthParams(mTLS);</div>
|
|
<div class="line"> ...</div>
|
|
<div class="line">}</div>
|
|
<div class="line">...</div>
|
|
</div><!-- fragment --><blockquote class="doxtable">
|
|
<p>NOTE: Certificates are finicky, and it is easy to make mistakes when generating a certificate chain yourself. 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> raises an error that says <code>Expected server name not found in chain</code>, double check that the common name, distinguished name, and issuer name are being set correctly (check out <a href="https://medium.com/@superseb/get-your-certificate-chain-right-4b117a9c0fce">this article</a> for how to do that). </p>
|
|
</blockquote>
|
|
<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>
|
|
<h2><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 Ethernet</h2>
|
|
<p>If you are using the <a href="https://github.com/arduino-libraries/Ethernet">Arduino Ethernet library</a> you will need to modify the library to support the large buffer sizes required by SSL (detailed in <a href="#resources">resources</a>). You can either modify the library yourself, or use <a href="https://github.com/OPEnSLab-OSU/EthernetLarge">this fork of the Ethernet library with the modification</a>. To use the fork: download a zipped copy of the fork through GiThub, use the "add a .zip library" button in Arduino to install the library, and replace <code>#include "Ethernet.h"</code> with <code>#include "EthernetLarge.h"</code> in your sketch. Alternatively if for some reason this solution does not work, you can apply the modification manually using the instructions below.</p>
|
|
<h3>Manual Modification</h3>
|
|
<p>First find the location of the library in the directory where Arduino is installed (<code>C:\Program Files (x86)\Arduino</code> on Windows). Inside of this directory, navigate to <code>libraries\Ethernet\src</code> (<code>C:\Program Files (x86)\Arduino\libraries\Ethernet\src</code> on Windows). Modify <code>Ethernet.h</code> to replace these lines: </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 & W5500 can have up to 8 sockets. Several bytes</div>
|
|
<div class="line">// of RAM are used for each socket. Reducing the maximum can save RAM, but</div>
|
|
<div class="line">// you are limited to fewer simultaneous connections.</div>
|
|
<div class="line">#if defined(RAMEND) && defined(RAMSTART) && ((RAMEND - RAMSTART) <= 2048)</div>
|
|
<div class="line">#define MAX_SOCK_NUM 4</div>
|
|
<div class="line">#else</div>
|
|
<div class="line">#define MAX_SOCK_NUM 8</div>
|
|
<div class="line">#endif</div>
|
|
<div class="line"> </div>
|
|
<div class="line">// By default, each socket uses 2K buffers inside the Wiznet chip. If</div>
|
|
<div class="line">// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting</div>
|
|
<div class="line">// this will use larger buffers within the Wiznet chip. Large buffers</div>
|
|
<div class="line">// can really help with UDP protocols like Artnet. In theory larger</div>
|
|
<div class="line">// buffers should allow faster TCP over high-latency links, but this</div>
|
|
<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 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 & W5500 can have up to 8 sockets. Several bytes</div>
|
|
<div class="line">// of RAM are used for each socket. Reducing the maximum can save RAM, but</div>
|
|
<div class="line">// you are limited to fewer simultaneous connections.</div>
|
|
<div class="line">#define MAX_SOCK_NUM 2</div>
|
|
<div class="line"> </div>
|
|
<div class="line">// By default, each socket uses 2K buffers inside the Wiznet chip. If</div>
|
|
<div class="line">// MAX_SOCK_NUM is set to fewer than the chip's maximum, uncommenting</div>
|
|
<div class="line">// this will use larger buffers within the Wiznet chip. Large buffers</div>
|
|
<div class="line">// can really help with UDP protocols like Artnet. In theory larger</div>
|
|
<div class="line">// buffers should allow faster TCP over high-latency links, but this</div>
|
|
<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>
|
|
<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>
|
|
<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="md__trust_anchors.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>Time</h3>
|
|
<p>The minimal x509 verification engine requires an accurate source of time to properly verify the creation and expiration dates of a certificate. As most embedded devices do not have a reliable source of time, 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> opts to use the compilation timestamp (<a href="https://gcc.gnu.org/onlinedocs/cpp/Standard-Predefined-Macros.html"><code>__DATE__</code> and <code>__TIME__</code></a>) as the "current time" during the verification process. While this approach reduces the complexity of 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>, it is inherently insecure, and can cause errors if certificates are redeployed (see <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/27">#27</a>): to accommodate these edge cases, <a class="el" href="class_s_s_l_client.html#ab285c2f5a03124558ef7f74b9f3d12ad" title="Change the time used during x509 verification to a different value.">SSLClient::setVerificationTime</a> can be used to update the timestamp before connecting, resolving the above issues.</p>
|
|
<h2>Resources</h2>
|
|
<p>The SSL/TLS protocol recommends a device support many different encryption and handshake algorithms. The complexity of these components results in many medium-footprint algorithms forming an extremely large whole. Compilation size of the <a href="examples/EthernetHTTPS/EthernetHTTPS.ino">EthernetHTTPS</a> example 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> <code>v1.6.11</code> for various boards is shown below:</p>
|
|
<table class="markdownTable">
|
|
<tr class="markdownTableHead">
|
|
<th class="markdownTableHeadLeft">Board </th><th class="markdownTableHeadLeft">Size </th></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft">Arduino Zero </td><td class="markdownTableBodyLeft"><pre>`RAM: [=== ] 33.7% (used 11052 bytes from 32768 bytes)`<br />
|
|
`Flash: [=== ] 34.7% (used 90988 bytes from 262144 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft">Arduino Due </td><td class="markdownTableBodyLeft"><pre>`RAM: [= ] 11.7% (used 11548 bytes from 98304 bytes)`<br />
|
|
`Flash: [== ] 16.7% (used 87572 bytes from 524288 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft">Adafruit Feather M0 </td><td class="markdownTableBodyLeft"><pre>`RAM: [==== ] 40.4% (used 13240 bytes from 32768 bytes)`<br />
|
|
`Flash: [==== ] 40.0% (used 104800 bytes from 262144 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft">ESP32 (Lolin32) </td><td class="markdownTableBodyLeft"><pre>`RAM: [= ] 6.9% (used 22476 bytes from 327680 bytes)`<br />
|
|
`Flash: [== ] 24.0% (used 314956 bytes from 1310720 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft">Teensy 3.0 </td><td class="markdownTableBodyLeft"><pre>`RAM: [======== ] 78.2% (used 12812 bytes from 16384 bytes)`<br />
|
|
`Flash: [======== ] 79.8% (used 104532 bytes from 131072 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft">Teensy 3.1 </td><td class="markdownTableBodyLeft"><pre>`RAM: [== ] 19.9% (used 13020 bytes from 65536 bytes)`<br />
|
|
`Flash: [==== ] 40.6% (used 106332 bytes from 262144 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft">Teensy 3.5 </td><td class="markdownTableBodyLeft"><pre>`RAM: [ ] 5.0% (used 12996 bytes from 262136 bytes)`<br />
|
|
`Flash: [== ] 20.1% (used 105476 bytes from 524288 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowEven">
|
|
<td class="markdownTableBodyLeft">Teensy 3.6 </td><td class="markdownTableBodyLeft"><pre>`RAM: [ ] 5.0% (used 13060 bytes from 262144 bytes)`<br />
|
|
`Flash: [= ] 10.2% (used 106828 bytes from 1048576 bytes)`</pre> </td></tr>
|
|
<tr class="markdownTableRowOdd">
|
|
<td class="markdownTableBodyLeft">Teensy 4.0 </td><td class="markdownTableBodyLeft"><pre>`RAM: [=== ] 25.9% (used 135860 bytes from 524288 bytes)`<br />
|
|
`Flash: [= ] 5.7% (used 115344 bytes from 2031616 bytes)`</pre> </td></tr>
|
|
</table>
|
|
<p>In addition to the above, most embedded processors lack the sophisticated math hardware commonly found in a modern CPU, which results in slow and memory intensive execution of these algorithms. Because of this, it is recommended 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> have 8kb of memory available on the stack during a connection, and 4-10 seconds should be allowed for the connection to complete. Note that this requirement is based on the SAMD21—more powerful processors (such as the ESP32) will see faster connection times.</p>
|
|
<blockquote class="doxtable">
|
|
<p>NOTE: 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>SSLClientImpl.h</code>, and <code>SSLClientImpl.cpp</code>. Unfortunately 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>
|
|
</blockquote>
|
|
<h2>Read Buffer Overflow</h2>
|
|
<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 have a cache large enough to store the entire payload. Since the device is typically already reading as fast as it can, we must increase the cache size in order to resolve this issue. 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 <code>MAX_SOCK_NUM</code> and <code>ETHERNET_LARGE_BUFFERS</code> macros show <a href="#manual-modification">here</a>), but mileage may vary with other drivers.</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 SSLClient::m_iobuf which can be expanded. Unfortunately, BearSSL limits the amount of data that can be put into the buffer based on the stage in the SSL handshake, and so increasing the buffer 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. 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 implementation would require in-depth knowledge of communication shield you are working with and a microcontroller with a significant amount of RAM, but would be the most robust solution available.</li>
|
|
</ul>
|
|
<h2>Cipher Support</h2>
|
|
<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/ssl_client_full.c">alternate one with support for older protocols</a>. To do this, edit <code>SSLClientImpl::SSLClientImpl</code> to change these lines: </p><div class="fragment"><div class="line"> {C++}</div>
|
|
<div class="line">br_client_init_TLS12_only(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div>
|
|
<div class="line">// comment the above line and uncomment the line below if you're having trouble connecting over SSL</div>
|
|
<div class="line">// br_ssl_client_init_full(&m_sslctx, &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(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num);</div>
|
|
<div class="line">// comment the above line and uncomment the line below if you're having trouble connecting over SSL</div>
|
|
<div class="line">br_ssl_client_init_full(&m_sslctx, &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>
|
|
<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>
|
|
<ul>
|
|
<li>In some drivers (Ethernet), calls to <code>Client::flush</code> will hang if internet is available but there is no route to the destination. Unfortunately <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> cannot correct for this without modifying the driver itself, and as a result the recommended solution is ensuring you choose a driver with built-in timeouts to prevent freezing. <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/13#issuecomment-643855923">More information here</a>.</li>
|
|
<li>Previous to <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> <code>v1.6.11</code>, <code><a class="el" href="class_s_s_l_client.html#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">SSLClient::write</a></code> would sometimes call <code>br_ssl_engine_sendapp_ack</code> with zero bytes, which resulted in a variety of issues including (but not limited to) and infinite recursion loop on the esp32 (<a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/9">#9</a>, <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/30">#30</a>).</li>
|
|
<li>Previous to <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> <code>v1.6.7</code>, calls to <code><a class="el" href="class_s_s_l_client.html#ad8ed697371748e31e01c3f697bc36cbe" title="Close the connection.">SSLClient::stop</a></code> would sometimes hang the device. More information in issue <a href="https://github.com/OPEnSLab-OSU/SSLClient/issues/13">https://github.com/OPEnSLab-OSU/SSLClient/issues/13</a>.</li>
|
|
<li>Previous to <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> <code>v1.6.6</code>, calls to <code><a class="el" href="class_s_s_l_client.html#ab97c0745f65a6c6009ac938b3b9912c3" title="Connect over SSL to a host specified by an IP address.">SSLClient::connect</a></code> would fail if the driver indicated that a socket was already opened (<code>Client::connected</code> returned true). This behavior created unintentional permanent failures when <code>Client::stop</code> would fail to close the socket, and as a result was downgraded to a warning in v1.6.6.</li>
|
|
<li>Previous to <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> <code>v1.6.3</code>, calling <code><a class="el" href="class_s_s_l_client.html#a03c7926938acd57cfc3b982edf725a86" title="Write some bytes to the SSL connection.">SSLClient::write</a></code> with more than 2kB of total data before flushing the write buffer would cause a buffer overflow. </li>
|
|
</ul>
|
|
</div></div><!-- PageDoc -->
|
|
</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="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>
|
|
</html>
|