150 lines
11 KiB
HTML
150 lines
11 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.8.20"/>
|
|
<meta name="viewport" content="width=device-width, initial-scale=1"/>
|
|
<title>SSLClient: Trust Anchors</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.9</span>
|
|
</div>
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
<!-- end header part -->
|
|
<!-- Generated by Doxygen 1.8.20 -->
|
|
<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');
|
|
/* @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('md__trust_anchors.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">Trust Anchors </div> </div>
|
|
</div><!--header-->
|
|
<div class="contents">
|
|
<div class="textblock"><h1>Background</h1>
|
|
<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#a68f026a625ca1ccd1aba87bb6e670376" 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>
|
|
<h1>Generating Trust Anchors</h1>
|
|
<p>Typically a trust anchor header file is generated using <a href="https://bearssl.org/gitweb/?p=BearSSL;a=tree;f=tools;h=0fa053e41d6bf88a28472f3b22dde41b21f14292;hb=dda1f8a0c46e15b4a235163470ff700b2f13dcc5">brssl</a>, a command-line utility included in BearSSL. As it is a fairly involded process to get brssl working, <a class="el" href="class_s_s_l_client.html" title="The main SSLClient class. Check out README.md for more info.">SSLClient</a> provides a number of alternative tools to make the generation process a bit easier.</p>
|
|
<p><b>Note:</b> When working with certificates (particularly in complicated mTLS setups), it can easily become confusing which certificate does what. If you aren't sure what certificate to put into the Trust Anchor tool, remember that Trust Anchors <em>only care about the verifying the server</em>: in other words, the certificate that goes into a Trust Anchor generation tool should be the certificate used to generate the server's certificate (usually a CA). Trust Anchors will never contain any information about client certificates, which should be passed into <a href="https://github.com/OPEnSLab-OSU/SSLClient#mtls">SSLClientParams</a> instead.</p>
|
|
<h2>HTTPS</h2>
|
|
<p>For HTTPS, there a couple of tools you can use. Ordered from easiest to hardest:</p><ul>
|
|
<li>This website, written to simplify the creation of trust anchor headers: <a href="https://openslab-osu.github.io/bearssl-certificate-utility/">https://openslab-osu.github.io/bearssl-certificate-utility/</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>The <code>brssl</code> 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>
|
|
</ul>
|
|
<h2>Other Connections</h2>
|
|
<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 --no-search</code> command to convert the certificate into a trust anchor header.</p>
|
|
<h1>Using Trust Anchors</h1>
|
|
<p>Once you've generated a trust anchor array, add it to your Arduino sketch using the <code>Sketch->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 "yourtrustanchorfile.h"</div>
|
|
<div class="line">// ...</div>
|
|
<div class="line">SSLClient 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#ab97c0745f65a6c6009ac938b3b9912c3" title="Connect over SSL to a host specified by an IP address.">SSLClient::connect</a></code> is called. </p>
|
|
</div></div><!-- contents -->
|
|
</div><!-- PageDoc -->
|
|
</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.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
|
|
</ul>
|
|
</div>
|
|
</body>
|
|
</html>
|