From bd890ae834c14ab9362614413cef27a61e693148 Mon Sep 17 00:00:00 2001 From: Noah Laptop Date: Sun, 24 Mar 2019 16:12:16 -0700 Subject: [PATCH] continued documenting, saftey commit before tinkering --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++---- src/SSLClient.h | 3 +-- 2 files changed, 43 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 5f10827..abf4799 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ **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.** -SSLClient is a simple library to add SSL [TLS 1.2](https://www.websecurity.symantec.com/security-topics/what-is-ssl-tls-https) functionality to any network library implementing the the [Arduino Client interface](https://www.arduino.cc/en/Reference/ClientConstructor), including the Arduino [EthernetClient](https://www.arduino.cc/en/Reference/EthernetClient) and [WiFiClient](https://www.arduino.cc/en/Reference/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. +SSLClient is a simple library to add [TLS 1.2](https://www.websecurity.symantec.com/security-topics/what-is-ssl-tls-https) functionality to any network library implementing the the [Arduino Client interface](https://www.arduino.cc/en/Reference/ClientConstructor), including the Arduino [EthernetClient](https://www.arduino.cc/en/Reference/EthernetClient) and [WiFiClient](https://www.arduino.cc/en/Reference/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. ## Overview @@ -30,7 +30,7 @@ SSLClient client(EthernetClient(), TAs, (size_t)2, A7); ``` Once that is setup, simply use SSLClient as you would the base client class: ```C++ -// connect to ardiuino.cc over ssl +// connect to ardiuino.cc over ssl (port 443 for websites) client.connect("www.arduino.cc", 443); // Make a HTTP request client.println("GET /asciilogo.txt HTTP/1.1"); @@ -43,11 +43,49 @@ client.flush(); // read and print the data ... ``` +**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](#Implementation-Notes). +For more information on SSLClient, check out the [examples](./examples), [API documentation](./docs/index.html), or the rest of this README. + +## How It Works + +SSLClient was created to integrate SSL seamlessly with the Arduino infrastructure, and so it does just that: implementing the brilliant [BearSSL](link-here) 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, helping debugging be a fast and simple process. The rest manages the state of BearSSL, and ensures a manageable memory footprint. + +## Implementation Notes + +Some ideas that didn't quite fit in the API documentation. + +### Certificate Verification + +SSLClient uses BearSSL's [minimal x509 verification engine](link-me) to verify the certificate of an SSL connection. This engine requires the developer create a trust anchor array using values stored in trusted root certificates. Check out [this document](./TrustAnchors.md) for more details on this component of SSLClient. + +### Cipher Support + +SSLClient supports only TLS1.2 and the ciphers listed in [this file under `suites[]`](./src/TLS12_only_profile) by default, and the list is relatively small to keep the connection secure and the flash footprint down. These ciphers should work for most applications, however if for some reason you would like to use an older version of TLS or a different cipher, you can change the BearSSL profile being used by SSLClient to an [alternate one with support for older protocols](./src/bearssl/src/ssl). To do this, edit `SSLClientImpl::SSLClientImpl` to change these lines: +```C++ +br_client_init_TLS12_only(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num); +// comment the above line and uncomment the line below if you're having trouble connecting over SSL +// br_ssl_client_init_full(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num); +``` +to this: +```C++ +// br_client_init_TLS12_only(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num); +// comment the above line and uncomment the line below if you're having trouble connecting over SSL +br_ssl_client_init_full(&m_sslctx, &m_x509ctx, m_trust_anchors, m_trust_anchors_num); +``` +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 [BearSSL Documentation](link-me) and I wish you the best of luck. + +### Resources + +The SSL protocol recommends a device support many different encryption algorithms, as well as protocols for SSL itself. The complexity of both of those components results in many medium sized components forming an extremely large whole. Additionally, most embedded processors lack the sophisticated math hardware commonly found in a modern CPU, and as a result require more instructions to create the encryption algorithms SSL requires. This not only increases size but makes the algorithms slow and memory intensive. + +To illustrate this, I will run some tests on various domains below. I haven't yet, but I will. + +If flash footprint is becoming a problem, there are numerous debugging strings (~3kb estimated) that can be removed from `SSLClient.h`, `SSLClientImpl.h`, and `SSLClientImpl.cpp`. 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. ### Logging -SSLClient also allows for changing the debugging level by adding an additional parameter to the constructor. +SSLClient also allows for changing the debugging level by adding an additional parameter to the constructor: ```C++ SSLClient client(EthernetClient(), TAs, (size_t)2, A7, SSL_INFO); ``` - The log levels are Logging is always outputted through the [Arduino Serial interface](https://www.arduino.cc/reference/en/language/functions/communication/serial/), so you'll need to setup Serial before you can view the SSL logs. +Logging is always outputted through the [Arduino Serial interface](https://www.arduino.cc/reference/en/language/functions/communication/serial/), so you'll need to setup Serial before you can view the SSL logs. Log levels are enumerated in [Error](./src/SSLClientImpl.h). The log level is set to `SSL_WARN` by default. \ No newline at end of file diff --git a/src/SSLClient.h b/src/SSLClient.h index d12ff56..e2b00cc 100644 --- a/src/SSLClient.h +++ b/src/SSLClient.h @@ -130,8 +130,7 @@ public: * the appropriete bearssl contexts. Due to the design of the SSL standard, * this function will probably take an extended period (1-4sec) to negotiate * the handshake and finish the connection. This function runs until the SSL - * handshake succeeds or fails, as found in most Arduino libraries, so be - * sure to design around this in your code. + * handshake succeeds or fails, as found in most Arduino libraries. * * The implementation for this function can be found in SSLClientImpl::connect(IPAddress, uint16_t) *