ESP32 WiFiClientSecure Library – setPrivateKey

Home / References / ESP32 Library / WiFiClientSecure

Description

The setPrivateKey method in the ESP32 WiFiClientSecure Library enables you to set the private key for a secure SSL/TLS connection. This method is critical when a server requires client authentication, pairing with a client certificate to prove the ESP32’s identity. At AvantMaker.com, we’re committed to empowering makers, learners, and enthusiasts by providing the tools and knowledge to secure your IoT projects effectively.


Syntax and Usage

The setPrivateKey method sets the private key used during the SSL/TLS handshake. Below is the syntax and a code snippet showing its usage:

void setPrivateKey(const char *private_key);

Here’s how to use it in your code:

  • Basic Usage with Private Key: Pass a null-terminated string containing the private key in PEM format. This method is typically used alongside setCACert and setCertificate for full client authentication.

There is only one way to use this method—by providing the private key as an argument. It must be called before connect() to apply the key to the TLS connection.

For practical applications and examples of this method, please consult the “Example Code” section on this page. This section provides comprehensive guidance to help you better understand and apply the method effectively.


Argument(s)

  • private_key (const char*): A pointer to a null-terminated string containing the private key in PEM format. This key authenticates the ESP32 client to the server during the SSL/TLS handshake and must correspond to the client certificate set by setCertificate.

Return Value

The setPrivateKey method does not return a value (it has a void return type). It configures the internal SSL context with the provided private key, and its success is reflected in the outcome of the subsequent connect() call.


Example Codes

The following example demonstrates how to use the setPrivateKey method to establish a secure SSL/TLS connection with client authentication. Before running the code, ensure you:

  • Replace placeholders (Your-WiFi-SSIDYour-WiFi-Password) with your WiFi credentials.
  • Generate and insert your own private key and client certificate as instructed in the code comments.
  • Verify the Root CA certificate matches your target server and is not expired (see this guide).

This code connects to www.httpbin.org, sends a POST request, and prints the server’s response. It won’t run without proper certificates and keys.

IMPORTANT – THIS CODE WILL NOT RUN AS IS

No private key or certificate is included in this example for security reasons. You MUST generate your own private key and certificate and insert them into the code to execute it.

/*
 * Author: Avant Maker
 * Date: March 6, 2025
 * Version: 1.0
 *
 * Description: This example demonstrate how to use 
 * ESP32 WiFiClientSecure Libary's 
 * setPrivateKey method to set a private key, 
 * ensuring a verified SSL/TLS connection.  
 *
 * ******************* WARNING *******************
 * No private key or certificate is included 
 * in this example for security reasons.
 * ************************************************
 * ********* THIS CODE WILL NOT RUN AS IS. ********
 * ************************************************
 * You MUST generate your own private key and 
 * certificate and insert them into the code to execute it.
 * ************************************************
 *
 * ATTENTION: The Root CA certificate has an expiration date. 
 * If the code fails to execute, it may be due to the Root CA
 * certificate has expired. Try obtaining the latest 
 * Root CA certificate and replacing the expired one in this code.
 * For detailed instructions on acquiring a website's
 * Root CA certificate, check out the link below:
 *
 * https://avantmaker.com/references/esp32-arduino-core-index/esp32-wificlientsecure-library/how-to-acquire-the-root-ca-certificate/
 *
 * License: MIT 
 * 
 * Code Source: This example code is sourced from the Comprehensive 
 * Guide to the ESP32 Arduino Core Library, accessible on 
 * AvantMaker.com. For additional code examples and in-depth 
 * documentation related to the ESP32 Arduino Core Library, 
 * please visit:
 *
 * https://avantmaker.com/references/esp32-arduino-core-index/
 *
 * AvantMaker.com, your premier destination for all things 
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated 
 * to empowering makers, learners, and enthusiasts with the resources
 * they need to bring their innovative ideas to life.
 */

#include <WiFi.h>
#include <NetworkClientSecure.h>

const char* ssid = "Your-WiFi-SSID";         // Replace with your WiFi SSID
const char* password = "Your-WiFi-Password"; // Replace with your WiFi password
const char* host = "www.httpbin.org";
const int port = 443;

// Root CA certificate for www.httpbin.org (update with your server's CA if different)
const char* rootCACert = R"literal(
-----BEGIN CERTIFICATE-----
MIIEXjCCA0agAwIBAgITB3MSSkvL1E7HtTvq8ZSELToPoTANBgkqhkiG9w0BAQsF
ADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6
b24gUm9vdCBDQSAxMB4XDTIyMDgyMzIyMjUzMFoXDTMwMDgyMzIyMjUzMFowPDEL
MAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEcMBoGA1UEAxMTQW1hem9uIFJT
QSAyMDQ4IE0wMjCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALtDGMZa
qHneKei1by6+pUPPLljTB143Si6VpEWPc6mSkFhZb/6qrkZyoHlQLbDYnI2D7hD0
sdzEqfnuAjIsuXQLG3A8TvX6V3oFNBFVe8NlLJHvBseKY88saLwufxkZVwk74g4n
WlNMXzla9Y5F3wwRHwMVH443xGz6UtGSZSqQ94eFx5X7Tlqt8whi8qCaKdZ5rNak
+r9nUThOeClqFd4oXych//Rc7Y0eX1KNWHYSI1Nk31mYgiK3JvH063g+K9tHA63Z
eTgKgndlh+WI+zv7i44HepRZjA1FYwYZ9Vv/9UkC5Yz8/yU65fgjaE+wVHM4e/Yy
C2osrPWE7gJ+dXMCAwEAAaOCAVowggFWMBIGA1UdEwEB/wQIMAYBAf8CAQAwDgYD
VR0PAQH/BAQDAgGGMB0GA1UdJQQWMBQGCCsGAQUFBwMBBggrBgEFBQcDAjAdBgNV
HQ4EFgQUwDFSzVpQw4J8dHHOy+mc+XrrguIwHwYDVR0jBBgwFoAUhBjMhTTsvAyU
lC4IWZzHshBOCggwewYIKwYBBQUHAQEEbzBtMC8GCCsGAQUFBzABhiNodHRwOi8v
b2NzcC5yb290Y2ExLmFtYXpvbnRydXN0LmNvbTA6BggrBgEFBQcwAoYuaHR0cDov
L2NydC5yb290Y2ExLmFtYXpvbnRydXN0LmNvbS9yb290Y2ExLmNlcjA/BgNVHR8E
ODA2MDSgMqAwhi5odHRwOi8vY3JsLnJvb3RjYTEuYW1hem9udHJ1c3QuY29tL3Jv
b3RjYTEuY3JsMBMGA1UdIAQMMAowCAYGZ4EMAQIBMA0GCSqGSIb3DQEBCwUAA4IB
AQAtTi6Fs0Azfi+iwm7jrz+CSxHH+uHl7Law3MQSXVtR8RV53PtR6r/6gNpqlzdo
Zq4FKbADi1v9Bun8RY8D51uedRfjsbeodizeBB8nXmeyD33Ep7VATj4ozcd31YFV
fgRhvTSxNrrTlNpWkUk0m3BMPv8sg381HhA6uEYokE5q9uws/3YkKqRiEz3TsaWm
JqIRZhMbgAfp7O7FUwFIb7UIspogZSKxPIWJpxiPo3TcBambbVtQOcNRWz5qCQdD
slI2yayq0n2TXoHyNCLEH8rpsJRVILFsg0jc7BaFrMnF462+ajSehgj12IidNeRN
4zl+EoNaWdpnWndvSpAEkq2P
-----END CERTIFICATE-----
)literal";

// ******************* WARNING *******************
// No private key or certificate is included 
// in this example for security reasons.
// ***********************************************
// ********* THIS CODE WILL NOT RUN AS IS. *******
// ***********************************************
// You MUST generate your own private key and 
// certificate and insert them into the code to execute it.
// ***********************************************
const char* privateKey = R"literal(
Paste your private key here (keep it secret!)
)literal";

const char* certificate = R"literal(
Paste your client certificate here (generate with openssl).
)literal";

NetworkClientSecure secureClient;

void setup() {
    Serial.begin(115200);
    WiFi.begin(ssid, password);
    while (WiFi.status() != WL_CONNECTED) {
        delay(500);
        Serial.print(".");
    }
    Serial.println("Connected to WiFi");

    secureClient.setCACert(rootCACert);
    secureClient.setCertificate(certificate);
    secureClient.setPrivateKey(privateKey);

    // Establish secure connection to server
    if (secureClient.connect(host, port)) {
        Serial.println("Connected to server");

        // Create the POST data
        String postData = "AvantMaker=HelloFromESP32";

        // Send the POST request
        secureClient.print("POST /post HTTP/1.1\r\n");
        secureClient.print("Host: www.httpbin.org\r\n");
        secureClient.print("Content-Type: application/x-www-form-urlencoded\r\n");
        secureClient.print("Content-Length: ");
        secureClient.print(postData.length());
        secureClient.print("\r\nConnection: close\r\n\r\n");
        secureClient.print(postData);

        // Wait for server response
        while (secureClient.connected() && !secureClient.available()) {
            delay(10);
        }

        // Read response 
        if (secureClient.available()) {
            String response = secureClient.readString();
            Serial.print("Server response:\n");
            Serial.println(response);
        } else {
            Serial.println("No data available");
        }

        secureClient.stop();

    } else {
        Serial.println("Failed to connect to server! Check the code description for solution.");
        return;
    }    
}

void loop() {

}

ESP32 Library Index

ESP32 Arduino Core Library


FAQ

Ready to experiment and explore more about ESP32? Visit our website’s All About ESP32 Resources Hub, packed with tutorials, guides, and tools to inspire your maker journey. Experiment, explore, and elevate your skills with everything you need to master this powerful microcontroller platform!

error: Content is protected !!