bearssl

BearSSL just doesn't address DTLS.  Otherwise it should be a full
client-server TLS implementation.

Author: lws-team

.sai.json

@@ -116,6 +116,10 @@
 			"cmake":	"-DLWS_WITH_GNUTLS=1",
 			"platforms":	"none, rocky9/aarch64-a72a55-rk3588/gcc"
 		},
+		"bearssl": {
+			"cmake":	"-DLWS_WITH_BEARSSL=1 -DLWS_BEARSSL_INCLUDE_DIRS=/opt/BearSSL/inc -DLWS_BEARSSL_LIBRARIES=/opt/BearSSL/build/libbearssl.so",
+			"platforms":	"none, rocky9/aarch64-a72a55-rk3588/gcc"
+		},
 		"default-examples-awslc": {
 			"cmake":	"-DLWS_WITH_AWSLC=1 -DLWS_OPENSSL_INCLUDE_DIRS=\"/usr/aws-lc/include\" -DLWS_OPENSSL_LIBRARIES=\"/usr/aws-lc/lib64/libssl.so;/usr/aws-lc/lib64/libcrypto.so\" -DLWS_WITH_MINIMAL_EXAMPLES=1",
 			"platforms":	"none, rocky9/aarch64-a72a55-rk3588/gcc"

CMakeLists-implied-options.txt

@@ -27,7 +27,7 @@ if(IOS)
     set(LWS_DETECTED_PLAT_IOS 1)
 endif()
 
-if (LWS_WITH_SCHANNEL OR LWS_WITH_GNUTLS OR LWS_WITH_MBEDTLS)
+if (LWS_WITH_SCHANNEL OR LWS_WITH_GNUTLS OR LWS_WITH_MBEDTLS OR LWS_WITH_BEARSSL)
        set(LWS_WITH_SSL 1)
 endif()
 
@@ -479,7 +479,7 @@ if (LWS_SSL_SERVER_WITH_ECDH_CERT)
 endif()
 
 # LWS_OPENSSL_SUPPORT deprecated... use LWS_WITH_TLS
-if (LWS_WITH_SSL OR LWS_WITH_MBEDTLS)
+if (LWS_WITH_SSL OR LWS_WITH_MBEDTLS OR LWS_WITH_BEARSSL)
 	set(LWS_OPENSSL_SUPPORT 1)
 	set(LWS_WITH_TLS 1)
 endif()

CMakeLists.txt

@@ -232,6 +232,8 @@ option(LWS_CTEST_INTERNET_AVAILABLE "CTest will performs tests that need the Int
 #
 option(LWS_WITH_SSL "Include SSL support (defaults to OpenSSL or similar, mbedTLS if LWS_WITH_MBEDTLS is set)" ON)
 option(LWS_WITH_MBEDTLS "Use mbedTLS (>=2.0) replacement for OpenSSL. When setting this, you also may need to specify LWS_MBEDTLS_LIBRARIES and LWS_MBEDTLS_INCLUDE_DIRS" OFF)
+option(LWS_WITH_BEARSSL "Use BearSSL replacement for OpenSSL. When setting this, you also may need to specify LWS_BEARSSL_LIBRARIES and LWS_BEARSSL_INCLUDE_DIRS" OFF)
+set(LWS_BEARSSL_PROFILE "full" CACHE STRING "BearSSL profile to use (e.g. full, client, minimal)")
 option(LWS_WITH_SCHANNEL "Use Windows SChannel for SSL" OFF)
 option(LWS_WITH_BORINGSSL "Use BoringSSL replacement for OpenSSL" OFF)
 option(LWS_WITH_GNUTLS "Use GnuTLS for SSL" OFF)

READMEs/README.build-windows.md

@@ -122,6 +122,16 @@ additional CMake options on lws:
       -DLWS_WITH_MBEDTLS=TRUE
 ```
 
+### Alternative: BearSSL (or OpenSSL/MbedTLS, see above)
+
+BearSSL is a highly optimized, minimalistic alternative to OpenSSL and MbedTLS. It is easily cross-compiled or built on Windows. Note that BearSSL currently does not support DTLS. To use it, simply provide the include and library paths:
+
+```
+      -DLWS_WITH_BEARSSL=TRUE
+      -DLWS_BEARSSL_INCLUDE_DIRS=C:/path/to/bearssl/inc
+      -DLWS_BEARSSL_LIBRARIES=C:/path/to/bearssl/build/bearssl.lib
+```
+
 ### Powershell
 
 CMake wants it and the version that comes with windows is too old to have pwsh.exe.

READMEs/README.build.md

@@ -334,6 +334,8 @@ plugins and lwsws.
  - If you are really restricted on memory, code size, or don't care about TLS
    speed, mbedTLS is a good choice: `cmake .. -DLWS_WITH_MBEDTLS=1`
 
+ - If you want an extremely lightweight, highly optimized TLS library with a minimal memory footprint and fast execution speed, BearSSL is a strong alternative: `cmake .. -DLWS_WITH_BEARSSL=1`. Note that BearSSL currently does not support DTLS.
+
  - If cpu and memory is not super restricted and you care about TLS speed,
    OpenSSL or a directly compatible variant like Boring SSL is a good choice.
 
@@ -354,12 +356,18 @@ Lws supports both almost the same, so instead of taking my word for it you are
 invited to try it both ways and see which the results (including, eg, binary
 size and memory usage as well as speed) suggest you use.
 
-NOTE: one major difference with mbedTLS is it does not load the system trust
-store by default.  That has advantages and disadvantages, but the disadvantage
-is you must provide the CA cert to lws built against mbedTLS for it to be able
-to validate it, ie, use -A with the test client.  The minimal test clients
-have the CA cert for warmcat.com and libwebsockets.org and use it if they see
-they were built with mbedTLS.
+NOTE: one major difference with mbedTLS and BearSSL is they do not natively load the OS trust
+store by default in the same way OpenSSL does.
+ 
+For mbedTLS, you must provide the CA cert to lws for it to be able
+to validate it, ie, use `-A` with the test client.
+
+For BearSSL, LWS implements a multi-cert PEM parser and fallback sequence to emulate OpenSSL's behavior:
+1. It checks the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables for runtime overrides.
+2. It falls back to probing standard OS locations (e.g. `/etc/ssl/certs/ca-certificates.crt`).
+3. It defaults to the CMake-configured `LWS_OPENSSL_CLIENT_CERTS` if all else fails.
+
+This allows BearSSL to validate most system certificates out of the box on Linux. The minimal test clients also automatically include the CA cert for warmcat.com if they see they were built with mbedTLS or BearSSL.
 
 @section optee Building for OP-TEE
 

cmake/lws_config.h.in

@@ -208,6 +208,7 @@
 #cmakedefine LWS_WITH_LWSAC
 #cmakedefine LWS_LOGS_TIMESTAMP
 #cmakedefine LWS_WITH_MBEDTLS
+#cmakedefine LWS_WITH_BEARSSL
 #cmakedefine LWS_WITH_SCHANNEL
 #cmakedefine LWS_WITH_GNUTLS
 #cmakedefine LWS_WITH_MINIZ

include/libwebsockets.h

@@ -907,6 +907,9 @@ lws_fx_string(const lws_fx_t *a, char *buf, size_t size);
 #include <mbedtls/sha256.h>
 #include <mbedtls/sha512.h>
 #endif
+#if defined(LWS_WITH_BEARSSL)
+#include <bearssl.h>
+#endif
 
 #include <libwebsockets/lws-genhash.h>
 #include <libwebsockets/lws-genrsa.h>

include/libwebsockets/lws-context-vhost.h

@@ -597,7 +597,7 @@ struct lws_context_creation_info {
 
 #endif
 
-#if !defined(LWS_WITH_MBEDTLS)
+#if !defined(LWS_WITH_MBEDTLS) && !defined(LWS_WITH_BEARSSL)
 	SSL_CTX *provided_client_ssl_ctx;
 	/**< CONTEXT: If non-null, swap out libwebsockets ssl
 	  * implementation for the one provided by provided_ssl_ctx.

include/libwebsockets/lws-genaes.h

@@ -91,6 +91,16 @@ struct lws_genaes_ctx {
 #elif defined(LWS_WITH_GNUTLS)
 	gnutls_cipher_hd_t ctx;
 	int gnutls_gcm_initialized;
+#elif defined(LWS_WITH_BEARSSL)
+	union {
+		br_aes_ct_cbcenc_keys cbcenc;
+		br_aes_ct_cbcdec_keys cbcdec;
+		br_aes_ct_ctr_keys ctr;
+	} u;
+	br_gcm_context gcm;
+	const br_block_cbcenc_class *cbcenc_vtable;
+	const br_block_cbcdec_class *cbcdec_vtable;
+	const br_block_ctr_class *ctr_vtable;
 #else
 	EVP_CIPHER_CTX *ctx;
 	const EVP_CIPHER *cipher;

include/libwebsockets/lws-genec.h

@@ -45,6 +45,11 @@ struct lws_genec_ctx {
 #elif defined(LWS_WITH_GNUTLS)
 	gnutls_privkey_t priv;
 	gnutls_pubkey_t pub;
+#elif defined(LWS_WITH_BEARSSL)
+	br_ec_public_key pub;
+	br_ec_private_key priv;
+	void *kbuf_priv;
+	void *kbuf_pub;
 #else
 	EVP_PKEY_CTX *ctx[2];
 #endif