diff --git a/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html b/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html new file mode 100644 index 0000000..125fbda --- /dev/null +++ b/docs/html/dir_386349f6a9bc1e2cd0767d257d5e5b91.html @@ -0,0 +1,112 @@ + + +
+ + + + +
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
+Files | |
file | trustanchors.h [code] |
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
+Files | |
file | trust_anchors.h [code] |
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
+Directories | |
directory | EthernetHTTPS |
directory | EthernetMultiHTTPS |
▼ readme | |
cert.h | |
▼ src | |
SSLClient.h | |
SSLClientImpl.cpp | |
SSLClientImpl.h | |
SSLSession.cpp | |
SSLSession.h | |
time_macros.h | |
TLS12_only_profile.c |
▼ examples | |
▼ EthernetHTTPS | |
trust_anchors.h | |
▼ EthernetMultiHTTPS | |
trustanchors.h | |
▼ readme | |
cert.h | |
▼ src | |
SSLClient.h | |
SSLClientImpl.cpp | |
SSLClientImpl.h | |
SSLSession.cpp | |
SSLSession.h | |
time_macros.h | |
TLS12_only_profile.c |
SSLClient 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.
+You can also view this README in doxygen.
SSLClient is a simple library to add TLS 1.2 functionality to any network library implementing the Arduino Client interface, including the Arduino EthernetClient and WiFiClient classes (though it is better to prefer WiFClient.connectSSL if implemented). In other words, SSLClient implements encrypted communication through SSL on devices that do not otherwise support it.
Using SSLClient should be similar to using any other Arduino-based Client class, since this library was developed around compatibility with EthernetClient. There are a few extra things, however, that you will need to get started:
Once all those are ready, you can create a simple SSLClient object like this:
Where:
TAs
.TAs_NUM
.AnalogPin - The analog pin to pull random data from (step 4).
-For example, if I am using EthernetClient, a generated array of 2 trust anchors, and the analog pin A7, I would declare an SSLClient instance using:
Once that is setup, simply use SSLClient as you would the base client class:
Note: client.connect("www.arduino.cc", 443)
can take 5-15 seconds to finish. This an unavoidable consequence of the SSL protocol, and is detailed in Implementation Notes.
For example, if I am using EthernetClient, a generated array of 2 trust anchors, and the analog pin A7, I would declare an SSLClient instance using:
Once that is setup, simply use SSLClient as you would the base client class:
Note: client.connect("www.arduino.cc", 443)
can take 5-15 seconds to finish. This an unavoidable consequence of the SSL protocol, and is detailed in Implementation Notes.
For more information on SSLClient, check out the examples, API documentation, or the rest of this README.
+For more information on SSLClient, check out the examples, API documentation, or the rest of this README.
SSLClient was created to integrate SSL seamlessly with the Arduino infrastructure, and so it does just that: implementing the brilliant BearSSL 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, and an implementation class SSLClientImpl. 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.
@@ -136,6 +137,10 @@ $(document).ready(function(){initNavTree('index.html','');});If you need to clear a session, you can do so using the SSLSession::removeSession function.
Some ideas that didn't quite fit in the API documentation.
+If you are using the Arduino Ethernet library, you will need to modify the library to support the large buffer sizes required by SSL (detailed in resources). To do this, first find the location of the library in the directory where Arduino is installed (C:\Program Files (x86)\Arduino
on Windows). Inside of this directory, navigate to libraries\Ethernet\src
(C:\Program Files (x86)\Arduino\libraries\Ethernet\src
on Windows). Modify Ethernet.h
to replace these lines:
With this:
You may need to use sudo
or administrator permissions to make this modification. We change MAX_SOCK_NUM
and ETHERNET_LARGE_BUFFERS
so the Ethernet hardware can allocate a larger space for SSLClient, 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.
The SSL protocol requires that SSLClient generate some random bits before connecting with a server. BearSSL provides a random number generator but requires a some entropy for a seed. 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, SSLClient uses a floating analog pin as an external source of random data, passed through to the constructor in the analog_pin
argument. Before every connection, SSLClient will take the bottom byte from 16 analog reads on analog_pin
, 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).
SSLClient uses BearSSL's minimal x509 verification 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 for more details on this component of SSLClient.
BearSSL also features a known certificate validation 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.
diff --git a/docs/html/navtreeindex0.js b/docs/html/navtreeindex0.js index 97904f6..adb9539 100644 --- a/docs/html/navtreeindex0.js +++ b/docs/html/navtreeindex0.js @@ -1,34 +1,34 @@ var NAVTREEINDEX0 = { -"_s_s_l_client_8h.html":[3,0,1,0], -"_s_s_l_client_8h.html#a0e14869de8f634ff2fb63826ae583569":[3,0,1,0,1], -"_s_s_l_client_8h_source.html":[3,0,1,0], -"_s_s_l_client_impl_8cpp.html":[3,0,1,1], -"_s_s_l_client_impl_8cpp.html#ad193a2cc121e0d4614a1c21eb463fb56":[3,0,1,1,0], -"_s_s_l_client_impl_8h.html":[3,0,1,2], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5":[3,0,1,2,2], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1218c16a5bf50589e0c498983851612c":[3,0,1,2,2,0], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1d5f8248fac85f56b05d49c7cb53494b":[3,0,1,2,2,3], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1d9afd51e0012e791f099657797c9aa9":[3,0,1,2,2,4], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5aaa79045423a355885738cd239dff6c2b":[3,0,1,2,2,1], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5adec799caf92b4fe2b6d2b362136f6ef6":[3,0,1,2,2,6], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5afb90a695332a7c96044dc97c577ee3c3":[3,0,1,2,2,2], -"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5afd588a56dcccf4f6943defa7ab699afc":[3,0,1,2,2,5], -"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395":[3,0,1,2,1], -"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d":[3,0,1,2,1,2], -"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a8c0bb62be3d0e6bfe5ed2f7ebbed3d91":[3,0,1,2,1,3], -"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395ad3f9f0591dcabc4fac1222c462bf17ec":[3,0,1,2,1,1], -"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395af16e73d8cce9a2c987bde5afe5524d7f":[3,0,1,2,1,0], -"_s_s_l_client_impl_8h_source.html":[3,0,1,2], -"_s_s_l_session_8cpp.html":[3,0,1,3], -"_s_s_l_session_8h.html":[3,0,1,4], -"_s_s_l_session_8h_source.html":[3,0,1,4], -"_t_l_s12__only__profile_8c.html":[3,0,1,6], -"_t_l_s12__only__profile_8c.html#a32c8112a1c37ba21a05952eeefc435f3":[3,0,1,6,0], +"_s_s_l_client_8h.html":[3,0,2,0], +"_s_s_l_client_8h.html#a0e14869de8f634ff2fb63826ae583569":[3,0,2,0,1], +"_s_s_l_client_8h_source.html":[3,0,2,0], +"_s_s_l_client_impl_8cpp.html":[3,0,2,1], +"_s_s_l_client_impl_8cpp.html#ad193a2cc121e0d4614a1c21eb463fb56":[3,0,2,1,0], +"_s_s_l_client_impl_8h.html":[3,0,2,2], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5":[3,0,2,2,2], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1218c16a5bf50589e0c498983851612c":[3,0,2,2,2,0], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1d5f8248fac85f56b05d49c7cb53494b":[3,0,2,2,2,3], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5a1d9afd51e0012e791f099657797c9aa9":[3,0,2,2,2,4], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5aaa79045423a355885738cd239dff6c2b":[3,0,2,2,2,1], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5adec799caf92b4fe2b6d2b362136f6ef6":[3,0,2,2,2,6], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5afb90a695332a7c96044dc97c577ee3c3":[3,0,2,2,2,2], +"_s_s_l_client_impl_8h.html#a2c3e4bb40f36b262a5214e2da2bca9c5afd588a56dcccf4f6943defa7ab699afc":[3,0,2,2,2,5], +"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395":[3,0,2,2,1], +"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a86c8fdfc38831619d5ed73dff5b0911d":[3,0,2,2,1,2], +"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395a8c0bb62be3d0e6bfe5ed2f7ebbed3d91":[3,0,2,2,1,3], +"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395ad3f9f0591dcabc4fac1222c462bf17ec":[3,0,2,2,1,1], +"_s_s_l_client_impl_8h.html#ab658e6d84759440dbf3c890446075395af16e73d8cce9a2c987bde5afe5524d7f":[3,0,2,2,1,0], +"_s_s_l_client_impl_8h_source.html":[3,0,2,2], +"_s_s_l_session_8cpp.html":[3,0,2,3], +"_s_s_l_session_8h.html":[3,0,2,4], +"_s_s_l_session_8h_source.html":[3,0,2,4], +"_t_l_s12__only__profile_8c.html":[3,0,2,6], +"_t_l_s12__only__profile_8c.html#a32c8112a1c37ba21a05952eeefc435f3":[3,0,2,6,0], "annotated.html":[2,0], -"cert_8h.html":[3,0,0,0], -"cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948":[3,0,0,0,0], -"cert_8h_source.html":[3,0,0,0], +"cert_8h.html":[3,0,1,0], +"cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948":[3,0,1,0,0], +"cert_8h_source.html":[3,0,1,0], "class_s_s_l_client.html":[2,0,0], "class_s_s_l_client.html#a0000d7f1e8656cf4a506a98133391fe0":[2,0,0,24], "class_s_s_l_client.html#a0699ff4b966162cba2ef59ff4a287270":[2,0,0,26], @@ -96,8 +96,11 @@ var NAVTREEINDEX0 = "class_s_s_l_session.html#acbe6549b55d50541d09a16f770e65afc":[2,0,2,7], "class_s_s_l_session.html#ae05648200cea66577f024d5d09a6fcbb":[2,0,2,0], "classes.html":[2,1], -"dir_68267d1309a1af8e8297ef4c3efbcdba.html":[3,0,1], -"dir_dfc5a9f91fbfb9426c406a3f10131a54.html":[3,0,0], +"dir_386349f6a9bc1e2cd0767d257d5e5b91.html":[3,0,0,1], +"dir_68267d1309a1af8e8297ef4c3efbcdba.html":[3,0,2], +"dir_9c42dc81377249a918256dbb9cfb2167.html":[3,0,0,0], +"dir_d28a4824dc47e487b107a5db32ef43c4.html":[3,0,0], +"dir_dfc5a9f91fbfb9426c406a3f10131a54.html":[3,0,1], "files.html":[3,0], "functions.html":[2,3,0], "functions_func.html":[2,3,1], @@ -112,27 +115,33 @@ var NAVTREEINDEX0 = "index.html":[], "md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html":[1], "pages.html":[], -"time__macros_8h.html":[3,0,1,5], -"time__macros_8h.html#a04e76e262f0920441e5f0c5552e83487":[3,0,1,5,19], -"time__macros_8h.html#a243cf438274412bbecf4b8d5eeb02ccb":[3,0,1,5,14], -"time__macros_8h.html#a2488d1ddab7e5fa119da3421462231c4":[3,0,1,5,1], -"time__macros_8h.html#a2af3d1d741ae2b49627adf56bbc95dc3":[3,0,1,5,20], -"time__macros_8h.html#a2d540510d5860d7f190d13124956bc57":[3,0,1,5,16], -"time__macros_8h.html#a38ac93dd8bfe385ff915a82c92bbfc97":[3,0,1,5,4], -"time__macros_8h.html#a3aaee30ddedb3f6675aac341a66e39e2":[3,0,1,5,15], -"time__macros_8h.html#a4dbe4cf7c879a2cdac386ce72c5e5994":[3,0,1,5,13], -"time__macros_8h.html#a56482fcc86a55713dee595c2092ed376":[3,0,1,5,5], -"time__macros_8h.html#a5ab60a7e3e1b6e0a919b3a37bc0d4b97":[3,0,1,5,8], -"time__macros_8h.html#a7f2cdee2eebbccd45c179a50a0bbabcf":[3,0,1,5,0], -"time__macros_8h.html#a868143e0521daf07b25a2f3947cf54a3":[3,0,1,5,6], -"time__macros_8h.html#a8cd8e04105fec7cd442d078c303e46b9":[3,0,1,5,18], -"time__macros_8h.html#a9da779a8ca64782ea49babce14122d34":[3,0,1,5,12], -"time__macros_8h.html#aad01b5fb233c0091aff2a837a8de32f4":[3,0,1,5,11], -"time__macros_8h.html#ab3592442029a102b388fafeadc4a6ab8":[3,0,1,5,2], -"time__macros_8h.html#ab6c76862964ff7e543fd9d5807b2fa79":[3,0,1,5,7], -"time__macros_8h.html#ac47b302f1b8d2a7a9c035c417247be76":[3,0,1,5,17], -"time__macros_8h.html#ac8f6b75d9e04634818984ba400d0dee1":[3,0,1,5,3], -"time__macros_8h.html#ae0574ced3f997b97d357c1cb68000e3a":[3,0,1,5,9], -"time__macros_8h.html#ae90924c33a05839b3eb1426472f40eb3":[3,0,1,5,10], -"time__macros_8h_source.html":[3,0,1,5] +"time__macros_8h.html":[3,0,2,5], +"time__macros_8h.html#a04e76e262f0920441e5f0c5552e83487":[3,0,2,5,19], +"time__macros_8h.html#a243cf438274412bbecf4b8d5eeb02ccb":[3,0,2,5,14], +"time__macros_8h.html#a2488d1ddab7e5fa119da3421462231c4":[3,0,2,5,1], +"time__macros_8h.html#a2af3d1d741ae2b49627adf56bbc95dc3":[3,0,2,5,20], +"time__macros_8h.html#a2d540510d5860d7f190d13124956bc57":[3,0,2,5,16], +"time__macros_8h.html#a38ac93dd8bfe385ff915a82c92bbfc97":[3,0,2,5,4], +"time__macros_8h.html#a3aaee30ddedb3f6675aac341a66e39e2":[3,0,2,5,15], +"time__macros_8h.html#a4dbe4cf7c879a2cdac386ce72c5e5994":[3,0,2,5,13], +"time__macros_8h.html#a56482fcc86a55713dee595c2092ed376":[3,0,2,5,5], +"time__macros_8h.html#a5ab60a7e3e1b6e0a919b3a37bc0d4b97":[3,0,2,5,8], +"time__macros_8h.html#a7f2cdee2eebbccd45c179a50a0bbabcf":[3,0,2,5,0], +"time__macros_8h.html#a868143e0521daf07b25a2f3947cf54a3":[3,0,2,5,6], +"time__macros_8h.html#a8cd8e04105fec7cd442d078c303e46b9":[3,0,2,5,18], +"time__macros_8h.html#a9da779a8ca64782ea49babce14122d34":[3,0,2,5,12], +"time__macros_8h.html#aad01b5fb233c0091aff2a837a8de32f4":[3,0,2,5,11], +"time__macros_8h.html#ab3592442029a102b388fafeadc4a6ab8":[3,0,2,5,2], +"time__macros_8h.html#ab6c76862964ff7e543fd9d5807b2fa79":[3,0,2,5,7], +"time__macros_8h.html#ac47b302f1b8d2a7a9c035c417247be76":[3,0,2,5,17], +"time__macros_8h.html#ac8f6b75d9e04634818984ba400d0dee1":[3,0,2,5,3], +"time__macros_8h.html#ae0574ced3f997b97d357c1cb68000e3a":[3,0,2,5,9], +"time__macros_8h.html#ae90924c33a05839b3eb1426472f40eb3":[3,0,2,5,10], +"time__macros_8h_source.html":[3,0,2,5], +"trust__anchors_8h.html":[3,0,0,0,0], +"trust__anchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948":[3,0,0,0,0,0], +"trust__anchors_8h_source.html":[3,0,0,0,0], +"trustanchors_8h.html":[3,0,0,1,0], +"trustanchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948":[3,0,0,1,0,0], +"trustanchors_8h_source.html":[3,0,0,1,0] }; diff --git a/docs/html/search/all_f.js b/docs/html/search/all_f.js index aa9c0c5..45a40de 100644 --- a/docs/html/search/all_f.js +++ b/docs/html/search/all_f.js @@ -1,9 +1,11 @@ var searchData= [ ['trust_20anchors',['Trust Anchors',['../md__c_1__users__noah__documents__arduino_libraries__s_s_l_client__trust_anchors.html',1,'']]], - ['tas_5fnum',['TAs_NUM',['../cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'cert.h']]], + ['tas_5fnum',['TAs_NUM',['../trust__anchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): trust_anchors.h'],['../trustanchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): trustanchors.h'],['../cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): cert.h']]], ['time_5fmacros_2eh',['time_macros.h',['../time__macros_8h.html',1,'']]], ['tls12_5fonly_5fprofile_2ec',['TLS12_only_profile.c',['../_t_l_s12__only__profile_8c.html',1,'']]], ['to_5fbr_5fsession',['to_br_session',['../class_s_s_l_session.html#acbe6549b55d50541d09a16f770e65afc',1,'SSLSession']]], + ['trust_5fanchors_2eh',['trust_anchors.h',['../trust__anchors_8h.html',1,'']]], + ['trustanchors_2eh',['trustanchors.h',['../trustanchors_8h.html',1,'']]], ['trustanchors_2emd',['TrustAnchors.md',['../_trust_anchors_8md.html',1,'']]] ]; diff --git a/docs/html/search/defines_5.js b/docs/html/search/defines_5.js index c10d695..5de0fdb 100644 --- a/docs/html/search/defines_5.js +++ b/docs/html/search/defines_5.js @@ -1,4 +1,4 @@ var searchData= [ - ['tas_5fnum',['TAs_NUM',['../cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'cert.h']]] + ['tas_5fnum',['TAs_NUM',['../trust__anchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): trust_anchors.h'],['../trustanchors_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): trustanchors.h'],['../cert_8h.html#ae2e26a4e8e97b0f15c18ba1ace062948',1,'TAs_NUM(): cert.h']]] ]; diff --git a/docs/html/search/files_3.js b/docs/html/search/files_3.js index 377b9b8..a75f15b 100644 --- a/docs/html/search/files_3.js +++ b/docs/html/search/files_3.js @@ -2,5 +2,7 @@ var searchData= [ ['time_5fmacros_2eh',['time_macros.h',['../time__macros_8h.html',1,'']]], ['tls12_5fonly_5fprofile_2ec',['TLS12_only_profile.c',['../_t_l_s12__only__profile_8c.html',1,'']]], + ['trust_5fanchors_2eh',['trust_anchors.h',['../trust__anchors_8h.html',1,'']]], + ['trustanchors_2eh',['trustanchors.h',['../trustanchors_8h.html',1,'']]], ['trustanchors_2emd',['TrustAnchors.md',['../_trust_anchors_8md.html',1,'']]] ]; diff --git a/docs/html/trust__anchors_8h.html b/docs/html/trust__anchors_8h.html new file mode 100644 index 0000000..a9424eb --- /dev/null +++ b/docs/html/trust__anchors_8h.html @@ -0,0 +1,131 @@ + + + + + + + +
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
Go to the source code of this file.
++Macros | |
#define | TAs_NUM 1 |
#define TAs_NUM 1 | +
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+
Go to the source code of this file.
++Macros | |
#define | TAs_NUM 2 |
#define TAs_NUM 2 | +
+ SSLClient
+ 1.0
+
+ Add TLS 1.2 functionality to any network library.
+ |
+