Skip to content

SSLClient - generic secure client Arduino library using mbedtls

License

Notifications You must be signed in to change notification settings

govorox/SSLClient

Repository files navigation

SSLClient Library for Arduino and ESP

govorox - SSLClient stars - SSLClient forks - SSLClient

GitHub tag License issues - SSLClient

Table of Contents

  1. Installation - How to install the library using Arduino or PlatformIO.
  2. Overview of this Library - An overview of the SSLClient library.
  3. What's New - The latest features and updates.
  4. Features - Key features of the SSLClient library.
  5. Usage - Basic usage examples for the SSLClient library.
  6. Overview of Functions - An overview of the API for leveraging MbedTLS.
  7. Contribute - Contributions are welcome!
  8. Change Log - See what's new in each release.
  9. Code Guide - Guidelines for contributing to the project.
  10. Signal Strength Map - Useful for debugging GSM connectivity.
  11. License - The license for the SSLClient library (open-source).

🔧 Installation

Install via the Arduino IDE or PlatformIO:

Arduino IDE - search for GovoroxSSLClient in the library manager.

PlatformIO - add digitaldragon/SSLClient@^1.3.1 to platformio.ini.

🚀 Overview

Originally based on the WiFiClientSecure for Arduino-ESP32 the SSLClient extends the ESP32/Arduino ecosystem to secure communication via TLS, providing a transparent SSL/TLS layer over any Client class instance. Leverages mbedtls for robust, efficient cryptographic operations, initially tailored for ESP32 but adaptable across platforms.

🌟 What's New in the Latest Release

  • Examples for PlatformIO and Arduino IDE: Updated examples to work with both PlatformIO and Arduino IDE for both Arduino-ESP32@2.0.17 and Arduino-ESP32@>3.0.0.

  • Major Versions 2 and 3 of MBedTLS: Updated to support the latest version of the MBedTLS library.

  • Feature flag for compatibility with MbedTLS v3.x.x - Automated by MBEDTLS_VERSION_MAJOR.

  • Add Flag MBEDTLS_BACKPORT to allow override MBEDTLS_VERSION_MAJOR >= 3.

  • Add workaround for W5500 Ethernet failing due to client returning -1 when no error - switch on flag W5500_WORKAROUND.

  • Close the following issues: Support for ESP32 and W5500 based Secure Ethernet for HTTPS or MQTTS? #44 and issue SSLClient with W5500 not working (works well with WiFi and TinyGSM) #85.

  • Improve documentation

  • Add GitHub Actions workflow to ensure PlatformIO examples compile.

  • Update GitHub Actions workflow to run tests multiple times with feature flags set.

  • Add GitHub Actions workflow to ensure Arduino IDE compile.

✨ Features

  • Secure TLS communication.
  • Based on Mbed-TLS/mbedtls.
    • Mbed TLS 2.x TLS Versions Supported: Mbed TLS 2.x supports TLS 1.0, TLS 1.1, and TLS 1.2. Specifics: TLS 1.2: Full support with a wide range of cipher suites and features. TLS 1.1 and 1.0: These versions are supported, but their use is discouraged due to security vulnerabilities and weaknesses compared to TLS 1.2.
    • Mbed TLS 3.x TLS Versions Supported: Mbed TLS 3.x supports TLS 1.2 and TLS 1.3. Specifics: TLS 1.2: Continues full support with extensive cipher suites and features. TLS 1.3: Introduced in Mbed TLS 3.x, providing enhanced security features, improved performance, and simplified handshake process.
  • Compatible with Arduino-ESP32 and potentially other platforms.
  • Suitable for IoT applications, including AWS IoT.

🛠 Usage

Basic Connection

#include <SSLClient.h>

// Initialize your transport layer (e.g., WiFi, GSM)
// A Client is anything which inherits from the Arduino Client class.
Client transport = /* Your transport layer */;

// Create SSLClient instance
SSLClient sslClient(&transport);

// Your setup code here...

AWS IoT Connectivity

TinyGsmClient transport(modem);
SSLClient secure(&transport);

// Set up certificates
secure.setCACert(AWS_CERT_CA);
secure.setCertificate(AWS_CERT_CRT);
secure.setPrivateKey(AWS_CERT_PRIVATE);

// Connect to MQTT broker on AWS endpoint
MQTTClient mqtt = MQTTClient(256);
mqtt.begin(AWS_IOT_ENDPOINT, 8883, secure);

📄 License

The library is released under GNU General Public Licence. See the LICENSE file for more details.