From f2fcf0eb941ce6fe6e1382ed52db420e8a65eaec Mon Sep 17 00:00:00 2001 From: cpq Date: Sun, 31 May 2026 17:41:58 +0100 Subject: [PATCH] Inline some docs into .h --- mongoose.h | 56 +++++++++++++++++++++++++++++++++++++++++++++--------- src/tls.h | 56 +++++++++++++++++++++++++++++++++++++++++++++--------- 2 files changed, 94 insertions(+), 18 deletions(-) diff --git a/mongoose.h b/mongoose.h index efb8d370..b6c2efae 100644 --- a/mongoose.h +++ b/mongoose.h @@ -1875,6 +1875,7 @@ int mg_http_status(const struct mg_http_message *hm); void mg_http_serve_ssi(struct mg_connection *c, const char *root, const char *fullpath); +// TLS / Security #define MG_TLS_NONE 0 // No TLS support @@ -1892,28 +1893,65 @@ void mg_http_serve_ssi(struct mg_connection *c, const char *root, +// TLS options structure passed to mg_tls_init(). All cert/key fields accept +// PEM strings or DER binary. +// +// One-way TLS: +// server sets `cert` + `key`, +// client sets `ca` + optionally `name` for hostname verification. +// +// Two-way (mutual) TLS: both sides set `ca` + `cert` + `key`. +// +// - `ca`: CA certificate. Verifies the peer's certificate. +// Set on clients to authenticate the server. Set on servers to require +// and verify a client certificate. If empty, peer is not verified. +// - `cert`: Our certificate. Required on servers. Also set on clients for +// mutual TLS. +// - `key`: Our private key. May equal `cert` when PEM bundles both. +// - `name`: Server name for SNI and hostname verification. Set on clients. +// Empty disables hostname verification. +// - `skip_verification`: Skip certificate and hostname verification. +// Useful during development; do not use in production. struct mg_tls_opts { - struct mg_str ca; // PEM or DER - struct mg_str cert; // PEM or DER - struct mg_str key; // PEM or DER - struct mg_str name; // If not empty, enable host name verification - int skip_verification; // Skip certificate and host name verification + struct mg_str ca; // CA certificate, PEM or DER + struct mg_str cert; // Our certificate, PEM or DER + struct mg_str key; // Our private key, PEM or DER + struct mg_str name; // Server name for SNI + hostname verification + bool skip_verification; // Skip certificate and hostname verification }; -void mg_tls_init(struct mg_connection *, const struct mg_tls_opts *opts); +// Initialise TLS on a connection. Call from the event handler on +// MG_EV_ACCEPT (server) or MG_EV_CONNECT (client). +// +// ```c +// // Server: one-way TLS +// if (ev == MG_EV_ACCEPT) { +// struct mg_tls_opts opts = {.cert = mg_str(s_tls_cert), +// .key = mg_str(s_tls_key)}; +// mg_tls_init(c, &opts); +// } +// +// // Client: verify server certificate and hostname +// if (ev == MG_EV_CONNECT) { +// struct mg_tls_opts opts = {.ca = mg_str(s_tls_ca), +// .name = mg_str("hostname")}; +// mg_tls_init(c, &opts); +// } +// ``` +void mg_tls_init(struct mg_connection *c, const struct mg_tls_opts *opts); + +// Private API, do not expose void mg_tls_free(struct mg_connection *); long mg_tls_send(struct mg_connection *, const void *buf, size_t len); long mg_tls_recv(struct mg_connection *, void *buf, size_t len); size_t mg_tls_pending(struct mg_connection *); void mg_tls_flush(struct mg_connection *); void mg_tls_handshake(struct mg_connection *); - -// Private void mg_tls_ctx_init(struct mg_mgr *); void mg_tls_ctx_free(struct mg_mgr *); #define MG_IS_DER(buf) (((uint8_t *) (buf))[0] == 0x30) // DER begins with 0x30 -// Low-level IO primives used by TLS layer +// Low-level IO primitives used by TLS layer enum { MG_IO_ERR = -1, MG_IO_WAIT = -2 }; long mg_io_send(struct mg_connection *c, const void *buf, size_t len); long mg_io_recv(struct mg_connection *c, void *buf, size_t len); diff --git a/src/tls.h b/src/tls.h index e5917eab..1e040b91 100644 --- a/src/tls.h +++ b/src/tls.h @@ -1,3 +1,4 @@ +// TLS / Security #pragma once #define MG_TLS_NONE 0 // No TLS support @@ -15,28 +16,65 @@ #include "tls_mbed.h" #include "tls_openssl.h" +// TLS options structure passed to mg_tls_init(). All cert/key fields accept +// PEM strings or DER binary. +// +// One-way TLS: +// server sets `cert` + `key`, +// client sets `ca` + optionally `name` for hostname verification. +// +// Two-way (mutual) TLS: both sides set `ca` + `cert` + `key`. +// +// - `ca`: CA certificate. Verifies the peer's certificate. +// Set on clients to authenticate the server. Set on servers to require +// and verify a client certificate. If empty, peer is not verified. +// - `cert`: Our certificate. Required on servers. Also set on clients for +// mutual TLS. +// - `key`: Our private key. May equal `cert` when PEM bundles both. +// - `name`: Server name for SNI and hostname verification. Set on clients. +// Empty disables hostname verification. +// - `skip_verification`: Skip certificate and hostname verification. +// Useful during development; do not use in production. struct mg_tls_opts { - struct mg_str ca; // PEM or DER - struct mg_str cert; // PEM or DER - struct mg_str key; // PEM or DER - struct mg_str name; // If not empty, enable host name verification - int skip_verification; // Skip certificate and host name verification + struct mg_str ca; // CA certificate, PEM or DER + struct mg_str cert; // Our certificate, PEM or DER + struct mg_str key; // Our private key, PEM or DER + struct mg_str name; // Server name for SNI + hostname verification + bool skip_verification; // Skip certificate and hostname verification }; -void mg_tls_init(struct mg_connection *, const struct mg_tls_opts *opts); +// Initialise TLS on a connection. Call from the event handler on +// MG_EV_ACCEPT (server) or MG_EV_CONNECT (client). +// +// ```c +// // Server: one-way TLS +// if (ev == MG_EV_ACCEPT) { +// struct mg_tls_opts opts = {.cert = mg_str(s_tls_cert), +// .key = mg_str(s_tls_key)}; +// mg_tls_init(c, &opts); +// } +// +// // Client: verify server certificate and hostname +// if (ev == MG_EV_CONNECT) { +// struct mg_tls_opts opts = {.ca = mg_str(s_tls_ca), +// .name = mg_str("hostname")}; +// mg_tls_init(c, &opts); +// } +// ``` +void mg_tls_init(struct mg_connection *c, const struct mg_tls_opts *opts); + +// Private API, do not expose void mg_tls_free(struct mg_connection *); long mg_tls_send(struct mg_connection *, const void *buf, size_t len); long mg_tls_recv(struct mg_connection *, void *buf, size_t len); size_t mg_tls_pending(struct mg_connection *); void mg_tls_flush(struct mg_connection *); void mg_tls_handshake(struct mg_connection *); - -// Private void mg_tls_ctx_init(struct mg_mgr *); void mg_tls_ctx_free(struct mg_mgr *); #define MG_IS_DER(buf) (((uint8_t *) (buf))[0] == 0x30) // DER begins with 0x30 -// Low-level IO primives used by TLS layer +// Low-level IO primitives used by TLS layer enum { MG_IO_ERR = -1, MG_IO_WAIT = -2 }; long mg_io_send(struct mg_connection *c, const void *buf, size_t len); long mg_io_recv(struct mg_connection *c, void *buf, size_t len);