cpp-httplib/docs-src/pages/en/tour/05-tls-setup.md at 54b3c1d072a5a6adeadcc79cfbd1be7afbbca71f

mirror of https://github.com/yhirose/cpp-httplib.git synced 2026-08-11 21:01:24 +00:00

Files

yhirose 54b3c1d072 Add Mbed TLS 4.x support (PSA Crypto) (#2502 )

* Add Mbed TLS 4.x support (PSA Crypto) for macOS

Auto-detect Mbed TLS 4.x via MBEDTLS_VERSION_MAJOR and adapt the backend:
- Include psa/crypto.h and drop the headers removed in 4.x (ctr_drbg,
  entropy, md5, sha*), gated behind the version macro.
- Compute MD5/SHA-256/SHA-512 via PSA (psa_hash_compute) and initialize
  PSA Crypto once with std::call_once.
- Drop the explicit entropy/CTR-DRBG RNG (PSA provides the TLS RNG) and
  skip the RNG-callback overloads of pk_parse_key/pk_check_pair on 4.x.
- Retry on a TLS 1.3 NewSessionTicket (the 4.x default) in connect, read,
  write and is_peer_closed via a single mbedtls_is_session_ticket() helper,
  so online HTTPS works, including large redirected downloads where the
  ticket arrives mid-write.

Note V4 implies V3, so 3.x-only paths now check V3 && !V4.

Build systems (macOS): the CMake config and pkg-config shipped by Homebrew
resolve 4.x transitively, so CMakeLists.txt and meson.build need no change
for linking; the Makefile links libtfpsacrypto when present, else
libmbedcrypto.

Tests: generate the encrypted client key as both PBES2-AES (3.6+/4.x,
OpenSSL, wolfSSL) and PBES1-3DES (Mbed TLS 2.28) and pick by version, since
4.x dropped DES and 2.28 lacks PBES2. Also generate the IP-host certs in
test/meson.build to match gen-certs.sh and CMakeLists.txt.

* CI: test Mbed TLS 4.x on macOS, 3.x on Ubuntu 26.04

Homebrew's default mbedtls is now 4.x, so switch the macOS build and CI job
to it (drop the mbedtls@3 pin). That leaves 3.x (Ubuntu 24.04 apt ships 2.28,
macOS now 4.x) uncovered, so add an ubuntu-26.04 job whose apt provides Mbed
TLS 3.6. Net coverage: 2.28 (ubuntu-latest), 3.6 (ubuntu-26.04), 4.2 (macOS).

ubuntu-26.04 is a public-preview runner image; fold it into the main ubuntu
matrix once ubuntu-latest moves to 26.04.

* Document Mbed TLS 4.x support and libtfpsacrypto rename

Update README.md and the tour's TLS setup pages (en/ja) to note that
Mbed TLS 4.x is now auto-detected and that it renames libmbedcrypto
to libtfpsacrypto.

2026-07-21 18:45:48 -04:00

2.9 KiB

Raw Blame History

title, order

title	order
TLS Setup	5

So far we've been using plain HTTP, but in the real world, HTTPS is the norm. To use HTTPS with cpp-httplib, you need a TLS library.

In this tour, we'll use OpenSSL. It's the most widely used option, and you'll find plenty of resources online.

Installing OpenSSL

Install it for your OS.

OS	How to install
macOS	Homebrew (`brew install openssl`)
Ubuntu / Debian	`sudo apt install libssl-dev`
Windows	vcpkg (`vcpkg install openssl`)

Compile Options

To enable TLS, define the CPPHTTPLIB_OPENSSL_SUPPORT macro when compiling. You'll need a few extra options compared to the previous chapters.

# macOS (Homebrew)
clang++ -std=c++17 -DCPPHTTPLIB_OPENSSL_SUPPORT \
    -I$(brew --prefix openssl)/include \
    -L$(brew --prefix openssl)/lib \
    -lssl -lcrypto \
    -framework CoreFoundation -framework Security \
    -o server server.cpp

# Linux
clang++ -std=c++17 -pthread -DCPPHTTPLIB_OPENSSL_SUPPORT \
    -lssl -lcrypto \
    -o server server.cpp

# Windows (Developer Command Prompt)
cl /EHsc /std:c++17 /DCPPHTTPLIB_OPENSSL_SUPPORT server.cpp libssl.lib libcrypto.lib

Let's look at what each option does.

-DCPPHTTPLIB_OPENSSL_SUPPORT — Defines the macro that enables TLS support
-lssl -lcrypto — Links the OpenSSL libraries
-I / -L (macOS only) — Points to the Homebrew OpenSSL paths
-framework CoreFoundation -framework Security (macOS only) — Needed to automatically load system certificates from the Keychain

Verifying the Setup

Let's make sure everything works. Here's a simple program that passes an HTTPS URL to httplib::Client.

#define CPPHTTPLIB_OPENSSL_SUPPORT
#include "httplib.h"
#include <iostream>

int main() {
    httplib::Client cli("https://www.google.com");

    auto res = cli.Get("/");
    if (res) {
        std::cout << "Status: " << res->status << std::endl;
    } else {
        std::cout << "Error: " << httplib::to_string(res.error()) << std::endl;
    }
}

Compile and run it. If you see Status: 200, your setup is complete.

Other TLS Backends

cpp-httplib also supports Mbed TLS and wolfSSL in addition to OpenSSL. You can switch between them just by changing the macro definition and linked libraries.

Backend	Macro	Libraries to link
OpenSSL	`CPPHTTPLIB_OPENSSL_SUPPORT`	`libssl`, `libcrypto`
Mbed TLS	`CPPHTTPLIB_MBEDTLS_SUPPORT`	`libmbedtls`, `libmbedx509`, `libmbedcrypto`
wolfSSL	`CPPHTTPLIB_WOLFSSL_SUPPORT`	`libwolfssl`

Mbed TLS 2.x, 3.x, and 4.x are all supported and auto-detected. Note that Mbed TLS 4.x renames libmbedcrypto to libtfpsacrypto, so link against that instead.

This tour assumes OpenSSL, but the API is the same regardless of which backend you choose.

Next Step

You're all set with TLS. Next, let's send a request to an HTTPS site.

Next: HTTPS Client

2.9 KiB Raw Blame History