|
| 1 | +## 📑 API Reference: `ESP_SSLClient` |
| 2 | + |
| 3 | +### ℹ️ Compatibility Note |
| 4 | + |
| 5 | +The following methods mirror the names and behavior of the **`WiFiClientSecure`** class in the **ESP8266 Arduino Core**, which also relies on the BearSSL library. This allows for seamless migration and feature consistency. |
| 6 | + |
| 7 | +*** |
| 8 | + |
| 9 | +### I. 🌐 Connection & Status |
| 10 | + |
| 11 | +| Method | Signature | Description | |
| 12 | +| :--- | :--- | :--- | |
| 13 | +| **`connect`** | `int connect(IPAddress ip, uint16_t port)` | Initiates a connection to the specified **IP address** and **port**. | |
| 14 | +| **`connect`** | `int connect(const char *host, uint16_t port)` | Initiates a connection to the specified **host name** and **port**. | |
| 15 | +| **`connect`** | `int connect(IPAddress ip, uint16_t port, int32_t timeout)` | Initiates connection to the **IP** and **port** with a maximum **timeout** (in milliseconds). | |
| 16 | +| **`connect`** | `int connect(const char *host, uint16_t port, int32_t timeout)` | Initiates connection to the **host** and **port** with a maximum **timeout** (in milliseconds). | |
| 17 | +| **`connectSSL`** | `bool connectSSL()` | **Upgrades** an existing plain TCP connection to **TLS/SSL** using the internally stored host/port details. | |
| 18 | +| **`connectSSL`** | `bool connectSSL(const char *host, uint16_t port)` | Compatibility wrapper for TLS handshake; uses **stored** host/port, ignoring parameters. | |
| 19 | +| **`connected`** | `uint8_t connected() override` | Returns 1 if the underlying network socket and SSL session are active and ready for I/O. | |
| 20 | +| **`stop`** | `void stop() override` | Terminates the connection and releases underlying network and SSL resources. | |
| 21 | +| **`isSecure`** | `bool isSecure() const` | Returns `true` if the current session is encrypted (SSL/TLS), `false` if it is plain TCP. | |
| 22 | +| **`validate`** | `void validate(const char *host, uint16_t port)` | Validates connection details against the current session; closes connection if **host** or **port** differs. | |
| 23 | +| **`operator bool`** | `operator bool() override` | Returns the connection status (`true` if connected). | |
| 24 | +| **`operator==`** | `bool operator==(const BSSL_TCPClient &rhs)` | Compares two client objects by checking the network client, port, and stored host. | |
| 25 | + |
| 26 | +*** |
| 27 | + |
| 28 | +### II. 💾 Data Transfer & Buffers |
| 29 | + |
| 30 | +| Method | Signature | Description | |
| 31 | +| :--- | :--- | :--- | |
| 32 | +| **`write`** | `size_t write(const uint8_t *buf, size_t size) override` | Writes **binary data** from a **buffer (`buf`)** of a specified **size** to the connection. | |
| 33 | +| **`write`** | `size_t write(const char *buf)` | Writes a null-terminated **C-style string (`buf`)** to the connection. | |
| 34 | +| **`write_P`** | `size_t write_P(PGM_P buf, size_t size)` | Writes data from a **Flash/PROGMEM buffer (`buf`)** of a specified **size**. | |
| 35 | +| **`read`** | `int read() override` | Reads a single byte (0-255) from the buffer, or returns -1. | |
| 36 | +| **`available`** | `int available() override` | Gets the total number of bytes currently available to read. | |
| 37 | +| **`peek`** | `int peek() override` | Reads the next available byte without consuming it. | |
| 38 | +| **`flush`** | `void flush() override` | Reads and discards all remaining data in the receive buffer. | |
| 39 | +| **`availableForWrite`** | `int availableForWrite() override` | Gets the number of bytes currently available for writing in the internal transmit buffer. | |
| 40 | +| **`peekBuffer`** | `const char *peekBuffer() EMBED_SSL_ENGINE_BASE_OVERRIDE` | Returns a pointer directly to the internal decrypted application data buffer. | |
| 41 | +| **`peekConsume`** | `void peekConsume(size_t consume) EMBED_SSL_ENGINE_BASE_OVERRIDE` | Notifies the SSL engine that **`consume`** bytes have been processed from the peek buffer. | |
| 42 | +| **`print`** | `int print(const char *data)` | Prints a null-terminated **C-style string (`data`)**. Returns bytes written. | |
| 43 | +| **`print`** | `int print(int data)` | Prints an **integer value (`data`)**. Returns bytes written. | |
| 44 | +| **`print`** | `int print(const String &data)` | Prints a **String object (`data`)** (non-AVR only). Returns bytes written. | |
| 45 | +| **`println`** | `int println(const char *data)` | Prints a **C-style string (`data`)** followed by CR+LF. | |
| 46 | +| **`println`** | `int println(int data)` | Prints an **integer value (`data`)** followed by CR+LF. | |
| 47 | +| **`println`** | `int println(const String &data)` | Prints a **String object (`data`)** followed by CR+LF (non-AVR only). | |
| 48 | + |
| 49 | +*** |
| 50 | + |
| 51 | +### III. ⚙️ Configuration & Validation |
| 52 | + |
| 53 | +| Method | Signature | Description | |
| 54 | +| :--- | :--- | :--- | |
| 55 | +| **`setClient`** | `void setClient(Client *client, bool enableSSL)` | Assigns the underlying network **client**; **enableSSL** sets the default security state. | |
| 56 | +| **`setSession`** | `void setSession(BearSSL_Session *session)` | Provides a memory location for **TLS session parameters** for faster connection resumption. | |
| 57 | +| **`setTimeout`** | `int setTimeout(uint32_t seconds)` | Sets the overall connection **timeout** duration in **seconds**. | |
| 58 | +| **`setHandshakeTimeout`** | `void setHandshakeTimeout(unsigned long handshake_timeout)` | Sets the maximum allowed duration for the SSL/TLS **handshake** in **seconds**. | |
| 59 | +| **`setSessionTimeout`** | `void setSessionTimeout(uint32_t seconds)` | Sets the maximum **idle time** before the TCP session is re-established (minimum 60s, 0 to disable). | |
| 60 | +| **`setDebugLevel`** | `void setDebugLevel(int level)` | Sets the **debug verbosity level** (0 for none). | |
| 61 | +| **`setBufferSizes`**| `void setBufferSizes(int recv, int xmit)` | Sets the desired **Receive (`recv`)** and **Transmit (`xmit`)** buffer sizes in bytes. | |
| 62 | +| **`setInsecure`** | `void setInsecure()` | Disables certificate verification for insecure connection testing. | |
| 63 | +| **`clearAuthenticationSettings`**| `void clearAuthenticationSettings()` | Clears all configured authentication settings (trust anchors, fingerprints, client certs). | |
| 64 | +| **`getLastSSLError`**| `int getLastSSLError(char *dest = NULL, size_t len = 0)` | Retrieves the last numeric SSL error code and optionally saves its description to **dest** buffer of **len** size. | |
| 65 | +| **`setX509Time`** | `void setX509Time(uint32_t now)` | Sets the current **UNIX epoch time** for certificate validity checking. | |
| 66 | +| **`setTrustAnchors`** | `void setTrustAnchors(const X509List *ta)` | Sets the list of trusted certificate authorities (**ta**) for chain validation. | |
| 67 | +| **`setKnownKey`** | `void setKnownKey(const PublicKey *pk, unsigned usages)` | Sets a known public key for verification, bypassing certificate chain validation. | |
| 68 | +| **`setFingerprint`** | `bool setFingerprint(const uint8_t fingerprint[20])` | Verifies the server certificate's SHA256 **fingerprint** (binary). | |
| 69 | +| **`setCertificate`** | `void setCertificate(const char *client_ca)` | Sets the client **certificate buffer** (PEM/DER) for mutual authentication. | |
| 70 | +| **`loadCertificate`**| `bool loadCertificate(Stream &stream, size_t size)` | Reads and sets the client **certificate** from an **Arduino Stream**. | |
| 71 | +| **`probeMaxFragmentLength`**| `bool probeMaxFragmentLength(const char *host, uint16_t port, uint16_t len)` | Probes the server to determine if a specific Maximum Fragment Length (**MFL**) is supported by **hostname**. | |
0 commit comments