A flexible and secure SSL/TLS client library for Arduino, enabling encrypted communication (HTTPS, SMTPS, etc.) on virtually any board or external network interface (Ethernet, GSM, WiFiClient, etc.).

Supports ESP32, ESP8266, RP2040, STM32, SAMD, Teensy, and AVR (with external SRAM). Compatible with WiFiClient, EthernetClient, GSMClient, and ESP-Mail-Client.

1. 🔧 Features
2. 📦 Supported Platforms
3. 🚀 Getting Started
   • ✅ Installation
   • 📋 Requirements
4. 🧠 Memory Usage Discrepancy Note
5. 📦 Buffer Configuration Guide
   • 🧠 Notes
6. 🧪 Basic Usage
7. 🧰 API Highlights
8. 🔬 Performance Profile Summary (Insecure Mode)
9. 🧠 Memory Expansion Guide (AVR)
10. 🧰 Macro Summary
11. 🌐 Duplex Mode Guide: When to Use Half-Duplex
12. 🧪 Diagnostic Tips
13. 📊 Supported Algorithms
14. 📄 License

• 🛡️ Secure Data: Data encryption via BearSSL (native or bundled)
• ⬆️ Duplex Modes: Supports Full-Duplex (simultaneous RX/TX) and Half-Duplex (sequential RX or TX) operation for advanced memory optimization.
• 🔄 TLS Upgrade: Support for protocol negotiation (e.g., STARTTLS)
• 🌟 Supported Protocols: TLS1.0, TLS1.1, and TLS1.2.
• 🔐 Validation: Full Certificate validation or quick testing via setInsecure() mode
• 🔁 Runtime Flexibility: Client switching at runtime via pointer assignment
• 📦 Configurable Buffers: Adjust RX/TX buffer sizes (512–16384 bytes)
• 🧪 Debugging: Multiple debugging levels and detailed error string support
• 📁 CertStore: Root Certificate management via filesystem APIs
• 🧩 Integration: Seamless integration with ESP-Mail-Client
• 🧠 Memory Management: Static and dynamic memory allocation support

• ESP32, ESP8266
• Raspberry Pi Pico / RP2040
• Arduino Nano RP2040 Connect
• STM32, SAMD, Teensy 3.1–4.1
• Arduino UNO R4 WiFi (Renesas)
• AVR boards (e.g., Arduino Mega 2560 with external SRAM)

• WIZnet W5100 / W5500 / Wxxx series (Ethernet)
• ENC28J60 (via lwIP)
• GSM modules
• Standard WiFi modules

⚠️ Note on Native Ethernet: Native PHY Ethernet chips (LAN8720, TLK101, etc.) are supported by ESP32 Core via WiFiClientSecure and ETH.h. This library is generally not required in those specific cases.

You can install ESP_SSLClient via:

• Arduino Library Manager: Search for ESP_SSLClient and click Install
• Manual Installation:
  1. Download the ZIP from GitHub Releases
  2. Extract to your libraries/ folder
  3. Restart the Arduino IDE

Users observing memory usage on modern 32-bit platforms (e.g., ESP32, Teensy 4.x) may see higher total RAM Usage (variables + code) compared to highly constrained microcontrollers like SAMD or AVR.

This difference is primarily due to the platform's execution model, not the library's overhead:

1. Low-SRAM Devices (AVR/SAMD): On these chips, the memory usage reported (often below 10 KB) accurately reflects the library's core static data and global variables. The executable code remains primarily in Flash.
2. High-Performance Devices (ESP/Teensy): On these architectures, the compiler and linker are optimized for speed. They often map large portions of the executable code (up to 120 KB, as seen on Teensy 4.x) from Flash memory directly into high-speed Data RAM (ITCM/OCRAM) for faster execution.

Therefore, while this library's core data overhead remains small and stable (e.g., $\approx 7-15\text{ KB}$ on all chips), the Total RAM Usage figure is inflated by the platform's aggressive performance optimization.

Always refer to the Variable/Static usage metrics to gauge the library's true memory footprint.

This table summarizes recommended buffer sizes based on duplex mode and expected payload size. Adjust these macros in your sketch or platformio.ini for optimal performance.

• Minimum RX size: 2048 bytes recommended to handle TLS record + headers.
• TX buffer: 512 bytes is sufficient for most request headers.
• Fragmentation: If server supports Maximum Fragment Length Negotiation (MFLN), smaller buffers may work.
• BearSSL: Can internally fragment large writes, but RX must still accommodate full record.

// --- 1. OPTIMIZATION MACROS ---
// Define these globally (before any library includes) to enable compile-time memory optimization.
// NOTE: These flags define the physical memory reserved by the client object.

#define SSLCLIENT_HALF_DUPLEX 

// The Receive (RX/In) buffer size should ideally be 16709 bytes (16384 max payload + 325 overhead)
// to safely accommodate any standard TLS record.
// 
// NOTE: A minimum size of 2048 bytes is required here because the specific application 
// (HTTP response headers/body) is expected to contain a large payload, factoring in TLS overhead.
#define STATIC_IN_BUFFER_SIZE 2048

// The Transmit (TX/Out) buffer size should ideally be 16469 bytes (16384 max payload + 85 overhead)
// to safely handle the largest possible outgoing TLS record.
// NOTE: This macro is ignored when SSLCLIENT_HALF_DUPLEX is defined.
#define STATIC_OUT_BUFFER_SIZE 512

#include <ESP_SSLClient.h>
#include <EthernetClient.h> 

EthernetClient basic_client; 
ESP_SSLClient ssl_client;

void setup() {
    Serial.begin(115200);

    // Starting network connection
    Ethernet.begin();

    Serial.print(F("ESP_Client version "));
    Serial.println(ESP_SSLCLIENT_VERSION);

    // 2. Assign the underlying network interface immediately.
    ssl_client.setClient(&basic_client);
    
    // 3. Set buffer sizes (Conditionally called only if buffers are NOT static)
    // NOTE: If the STATIC macros above were defined, setBufferSizes() is either ignored or
    // its parameters are used to determine the static buffer size.
#if !defined(STATIC_IN_BUFFER_SIZE) || !defined(STATIC_OUT_BUFFER_SIZE)
    ssl_client.setBufferSizes(2048, 512);
#endif

    // 4. Set security policy 
    ssl_client.setInsecure();
    ssl_client.setDebugLevel(3); 

    Serial.println(F("Connecting to the server..."));

    // --- Connection ---
    if (ssl_client.connect("reqres.in", 443))
    {
        Serial.println(F("Connected via TLS. Sending request..."));
        
        // NOTE: This standard HTTP/1.1 request-response pattern is strictly sequential, 
        // making it ideally suited for the RAM-saving Half-Duplex mode. 
        ssl_client.print(F("POST /api/users HTTP/1.1\r\n"));
        ssl_client.print(F("Host: reqres.in\r\n"));
        ssl_client.print(F("Content-Type: application/json\r\n"));
        ssl_client.print(F("Connection: close\r\n")); 
        ssl_client.print(F("Content-Length: 34\r\n")); 
        ssl_client.print(F("\r\n")); 
        ssl_client.print(F("{\"name\":\"morpheus\",\"job\":\"leader\"}"));
    } else {
        Serial.println(F("Connection failed."));
    }

    // --- Response Reading & Cleanup ---
    
    // 5. Normally for effectiveness, the response reading should be done in loop()
    // If the response is processed in the local function, it should be wait for 
    // its available before reading 
    while (!ssl_client.available())
        delay(0); // WARNING: tight loop for minimal systems. Use millis() timer for production.
        
    while (ssl_client.available())
        Serial.print((char)ssl_client.read());

    if (!ssl_client.connected()) {
        ssl_client.stop();
        Serial.println(F("\nConnection closed."));
        while(true) delay(100); 
    }
}

void loop() {
    // loop() remains empty as the example completes in setup().
}

Full API: src/Readme.md or src/client/TCPClient.h

This table shows the resource consumption when built with maximum resource conservation using the following static, minimized, and unsecured configuration:

#define SSLCLIENT_INSECURE_ONLY
#define STATIC_IN_BUFFER_SIZE 512
#define STATIC_OUT_BUFFER_SIZE 512
#define STATIC_X509_CONTEXT
#define STATIC_SSLCLIENT_CONTEXT

By allowing the debug and the debug information string by defining ENABLE_DEBUG and ENABLE_ERROR_STRING will increase the program space.

Note: Debug and error string options are disabled and no netork client library included in the compilation result below for minimum program space.

For Arduino Mega 2560, native 8 KB SRAM is insufficient for SSL/TLS. Use external memory:

• Recommended: Parallel SRAM shields (e.g., XMEM+, QuadRAM)
• Benefits:
  • External memory is mapped into CPU address space
  • Standard malloc() and new use external RAM
  • Stack relocation eliminates overflow risks

Define these in your main sketch or platformio.ini to customize the build.

• Use setDebugLevel(4) to trace the BearSSL handshake step-by-step for connection issues.
• Define ENABLE_ERROR_STRING to get readable error messages instead of just error codes.
• Use setInsecure() if testing connectivity is your first goal (before implementing cert validation).
• Check buffer sizes if handshake fails (try increasing them, e.g., 2048/1024).
• Validate transport client lifetime—ensure the client pointer you pass to setClient() remains valid.

The core BearSSL implementation included in this library supports a comprehensive suite of modern and necessary cryptographic primitives:

MIT License

Copyright (c) 2026 Suwatchai K.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.