feat!: the Mbed TLS stream asks a credentials source for its material

Bdd/Targets/Common/BddTargetTlsSender_MbedTls_LwipRawTcp.c

@@ -28,6 +28,7 @@
 #include "BddTargetTlsConfig.h"
 #include "SolidSyslogLwipRawAddress.h"
 #include "SolidSyslogLwipRawTcpStream.h"
+#include "SolidSyslogMbedTlsHandleCredentials.h"
 #include "SolidSyslogMbedTlsStream.h"
 #include "SolidSyslogNullSender.h"
 #include "SolidSyslogStream.h"
@@ -56,6 +57,7 @@
 struct SolidSyslogResolver;
 
 static struct SolidSyslogStream* underlyingStream;
+static struct SolidSyslogMbedTlsCredentials* credentials;
 static struct SolidSyslogStream* tlsStream;
 static struct SolidSyslogAddress* address;
 static struct SolidSyslogSender* sender;
@@ -378,13 +380,18 @@ struct SolidSyslogSender* BddTargetTlsSender_Create(struct SolidSyslogResolver*
     tlsStreamConfig.Transport = underlyingStream;
     tlsStreamConfig.Sleep = RtosSleep;
     tlsStreamConfig.Rng = &drbg;
-    tlsStreamConfig.CaChain = &caChain;
     /* Plain-TLS and mTLS share one SNI on this oracle (CN/SAN = "syslog-ng"),
      * so BddTargetTlsConfig_GetServerName and BddTargetMtlsConfig_GetServerName
      * return the same string. Use the TLS one to make the equivalence explicit. */
     tlsStreamConfig.ServerName = BddTargetTlsConfig_GetServerName();
-    tlsStreamConfig.ClientCertChain = &clientCertChain;
-    tlsStreamConfig.ClientKey = &clientKey;
+    static struct SolidSyslogMbedTlsHandleCredentialsConfig credentialsConfig;
+    credentialsConfig = (struct SolidSyslogMbedTlsHandleCredentialsConfig) {0};
+    credentialsConfig.Rng = &drbg;
+    credentialsConfig.CaChain = &caChain;
+    credentialsConfig.ClientCertChain = &clientCertChain;
+    credentialsConfig.ClientKey = &clientKey;
+    credentials = SolidSyslogMbedTlsHandleCredentials_Create(&credentialsConfig);
+    tlsStreamConfig.Credentials = credentials;
     tlsStream = SolidSyslogMbedTlsStream_Create(&tlsStreamConfig);
 
     address = SolidSyslogLwipRawAddress_Create();
@@ -414,6 +421,7 @@ void BddTargetTlsSender_Destroy(void)
     SolidSyslogStreamSender_Destroy(sender);
     SolidSyslogLwipRawAddress_Destroy(address);
     SolidSyslogMbedTlsStream_Destroy(tlsStream);
+    SolidSyslogMbedTlsHandleCredentials_Destroy(credentials);
     SolidSyslogLwipRawTcpStream_Destroy(underlyingStream);
 
     /* Entropy / DRBG / parsed certs survive across Destroy -> Create cycles to

Bdd/Targets/Common/BddTargetTlsSender_MbedTls_PlusTcpTcp.c

@@ -27,6 +27,7 @@
 #include "BddTargetTlsConfig.h"
 #include "SolidSyslogPlusTcpAddress.h"
 #include "SolidSyslogPlusTcpTcpStream.h"
+#include "SolidSyslogMbedTlsHandleCredentials.h"
 #include "SolidSyslogMbedTlsStream.h"
 #include "SolidSyslogNullSender.h"
 #include "SolidSyslogStream.h"
@@ -55,6 +56,7 @@
 struct SolidSyslogResolver;
 
 static struct SolidSyslogStream* underlyingStream;
+static struct SolidSyslogMbedTlsCredentials* credentials;
 static struct SolidSyslogStream* tlsStream;
 static struct SolidSyslogAddress* address;
 static struct SolidSyslogSender* sender;
@@ -367,13 +369,18 @@ struct SolidSyslogSender* BddTargetTlsSender_Create(struct SolidSyslogResolver*
     tlsStreamConfig.Transport = underlyingStream;
     tlsStreamConfig.Sleep = RtosSleep;
     tlsStreamConfig.Rng = &drbg;
-    tlsStreamConfig.CaChain = &caChain;
     /* Plain-TLS and mTLS share one SNI on this oracle (CN/SAN = "syslog-ng"),
      * so BddTargetTlsConfig_GetServerName and BddTargetMtlsConfig_GetServerName
      * return the same string. Use the TLS one to make the equivalence explicit. */
     tlsStreamConfig.ServerName = BddTargetTlsConfig_GetServerName();
-    tlsStreamConfig.ClientCertChain = &clientCertChain;
-    tlsStreamConfig.ClientKey = &clientKey;
+    static struct SolidSyslogMbedTlsHandleCredentialsConfig credentialsConfig;
+    credentialsConfig = (struct SolidSyslogMbedTlsHandleCredentialsConfig) {0};
+    credentialsConfig.Rng = &drbg;
+    credentialsConfig.CaChain = &caChain;
+    credentialsConfig.ClientCertChain = &clientCertChain;
+    credentialsConfig.ClientKey = &clientKey;
+    credentials = SolidSyslogMbedTlsHandleCredentials_Create(&credentialsConfig);
+    tlsStreamConfig.Credentials = credentials;
     tlsStream = SolidSyslogMbedTlsStream_Create(&tlsStreamConfig);
 
     address = SolidSyslogPlusTcpAddress_Create();
@@ -403,6 +410,7 @@ void BddTargetTlsSender_Destroy(void)
     SolidSyslogStreamSender_Destroy(sender);
     SolidSyslogPlusTcpAddress_Destroy(address);
     SolidSyslogMbedTlsStream_Destroy(tlsStream);
+    SolidSyslogMbedTlsHandleCredentials_Destroy(credentials);
     SolidSyslogPlusTcpTcpStream_Destroy(underlyingStream);
 
     /* Entropy / DRBG / parsed certs survive across Destroy -> Create cycles to

Platform/MbedTls/CMakeLists.txt

@@ -12,6 +12,8 @@ add_library(SolidSyslogMbedTls INTERFACE)
 # Unused TUs dead-strip at link time (-Wl,--gc-sections).
 target_sources(SolidSyslogMbedTls INTERFACE
     ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsNullCredentials.c
+    ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsHandleCredentials.c
+    ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsHandleCredentialsStatic.c
     ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsStream.c
     ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsStreamStatic.c
     ${CMAKE_CURRENT_SOURCE_DIR}/Source/SolidSyslogMbedTlsHmacSha256Policy.c

Platform/MbedTls/Interface/SolidSyslogMbedTlsHandleCredentials.h

@@ -0,0 +1,64 @@
+/* SPDX-FileCopyrightText: Copyright 2026 Cozens Software Solutions Limited
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0 OR LicenseRef-COSOSO-Commercial
+ */
+
+/** @file
+ *  An Mbed TLS credentials backend that carries caller-built, caller-owned
+ *  mbedTLS handles. The integrator parses its own PEM, unwraps its own key, or
+ *  fetches material from wherever it lives, and hands the resulting handles
+ *  here; this library parses nothing and owns nothing.
+ *
+ *  The handles must outlive the credentials, because every connection installs
+ *  the same ones. A backend that acquires material per connection - one parsing
+ *  a PEM buffer on demand, or reaching a secure element - is a different
+ *  implementation of the same role. */
+#ifndef SOLIDSYSLOGMBEDTLSHANDLECREDENTIALS_H
+#define SOLIDSYSLOGMBEDTLSHANDLECREDENTIALS_H
+
+#include "SolidSyslogExternC.h"
+
+/* Forward declarations keep the header free of any mbedTLS include, as the
+ * stream header does. Integrators include the relevant mbedTLS headers
+ * themselves before this one to bring the types into scope. */
+struct mbedtls_ctr_drbg_context;
+struct mbedtls_pk_context;
+struct mbedtls_x509_crt;
+
+SOLIDSYSLOG_EXTERN_C_BEGIN
+
+    struct SolidSyslogMbedTlsCredentials;
+
+    /** Where this backend's material lives. Every handle is caller-built and
+     *  caller-owned, and must stay valid for the lifetime of the credentials. */
+    struct SolidSyslogMbedTlsHandleCredentialsConfig
+    {
+        /** Trust anchors the peer certificate must chain to; NULL installs
+         *  none, which leaves the peer authorised only if the stream has
+         *  another means to do it. */
+        struct mbedtls_x509_crt* CaChain;
+        /** Leaf certificate (plus intermediates) for mutual TLS; NULL means no
+         *  client credential. Certificate and key are all-or-nothing -
+         *  supplying one without the other is reported. */
+        struct mbedtls_x509_crt* ClientCertChain;
+        /** Private key matching ClientCertChain; NULL means no client
+         *  credential. */
+        struct mbedtls_pk_context* ClientKey;
+        /** Seeded CTR-DRBG, used to check the client key against its
+         *  certificate; required - a NULL is reported at
+         *  SolidSyslogMbedTlsHandleCredentials_Create. The stream takes its own
+         *  handshake RNG separately, and the same one serves both. */
+        struct mbedtls_ctr_drbg_context* Rng;
+    };
+
+    /** Draw a credentials instance from the pool. A NULL config or a NULL Rng is
+     *  reported and falls back to the shared Null credentials, as does an
+     *  exhausted pool. */
+    struct SolidSyslogMbedTlsCredentials* SolidSyslogMbedTlsHandleCredentials_Create(
+        const struct SolidSyslogMbedTlsHandleCredentialsConfig* config
+    );
+    /** Release the pool slot. */
+    void SolidSyslogMbedTlsHandleCredentials_Destroy(struct SolidSyslogMbedTlsCredentials * base);
+
+SOLIDSYSLOG_EXTERN_C_END
+
+#endif /* SOLIDSYSLOGMBEDTLSHANDLECREDENTIALS_H */

Platform/MbedTls/Interface/SolidSyslogMbedTlsHandleCredentialsErrors.h

@@ -0,0 +1,39 @@
+/* SPDX-FileCopyrightText: Copyright 2026 Cozens Software Solutions Limited
+ * SPDX-License-Identifier: PolyForm-Noncommercial-1.0.0 OR LicenseRef-PolyForm-Internal-Use-1.0.0 OR LicenseRef-COSOSO-Commercial
+ */
+
+/** @file
+ *  Error codes and Source identity for the MbedTlsHandleCredentials backend. */
+#ifndef SOLIDSYSLOGMBEDTLSHANDLECREDENTIALSERRORS_H
+#define SOLIDSYSLOGMBEDTLSHANDLECREDENTIALSERRORS_H
+
+#include "SolidSyslogExternC.h"
+
+SOLIDSYSLOG_EXTERN_C_BEGIN
+
+    struct SolidSyslogErrorSource;
+
+    /** Detail codes for events whose Source is SolidSyslogMbedTlsHandleCredentialsErrorSource.
+     *  A handler reads these off event->Detail after matching event->Source; the
+     *  members name their own fault. */
+    enum SolidSyslogMbedTlsHandleCredentialsErrors
+    {
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_POOL_EXHAUSTED,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_UNKNOWN_DESTROY,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_NULL_CONFIG,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_NULL_RNG,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_CLIENT_CREDENTIAL_INCOMPLETE,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_CLIENT_CREDENTIAL_MISMATCHED,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_CLIENT_CREDENTIAL_NOT_INSTALLED,
+        SOLIDSYSLOG_MBEDTLS_HANDLE_CREDENTIALS_ERROR_MAX /**< One past the last code; never emitted. Bounds the range for iteration. */
+    };
+
+    /** Identity for events raised by an MbedTlsHandleCredentials. A handler
+     *  matches by address (event->Source == &SolidSyslogMbedTlsHandleCredentialsErrorSource),
+     *  then reads event->Detail as an enum
+     *  SolidSyslogMbedTlsHandleCredentialsErrors. */
+    extern const struct SolidSyslogErrorSource SolidSyslogMbedTlsHandleCredentialsErrorSource;
+
+SOLIDSYSLOG_EXTERN_C_END
+
+#endif /* SOLIDSYSLOGMBEDTLSHANDLECREDENTIALSERRORS_H */

Platform/MbedTls/Interface/SolidSyslogMbedTlsStream.h

@@ -11,8 +11,9 @@
  *  What the stream does through its vtable is the substance:
  *
  *  - Open first opens the underlying transport, applies the library-owned TLS
- *    policy (client mode, TLS 1.2 floor, VERIFY_REQUIRED against the CaChain),
- *    installs the peer identity, then drives the handshake to completion. The
+ *    policy (client mode, TLS 1.2 floor, VERIFY_REQUIRED), asks the credentials
+ *    source to install the material for this connection, installs the peer
+ *    identity, then drives the handshake to completion. The
  *    non-blocking transport means each mbedtls_ssl_handshake may want more I/O;
  *    the injected Sleep bridges those polls until the handshake completes, hits
  *    a hard error (HANDSHAKE_REJECTED), or the bounded budget expires
@@ -25,10 +26,12 @@
  *    other TLS return (alert, transport error) - fail-fast, and store-and-forward
  *    replays after the reconnect.
  *
- *  Peer identity is set by ServerName (see the config member). All key material
- *  is injected as caller-built, caller-owned mbedTLS handles - never file paths
- *  or PEM blobs. Coexistence contract: this adapter touches only per-instance
- *  ssl_config / ssl_context state and never calls process-global mbedTLS APIs
+ *  Peer identity is set by ServerName (see the config member). No key material
+ *  reaches this stream: it asks its credentials source to install onto the
+ *  ssl_config at Open and tells it at Close, so a deployment can keep material
+ *  out of memory between connections. Coexistence contract: this adapter touches
+ *  only per-instance ssl_config / ssl_context state and never calls
+ *  process-global mbedTLS APIs
  *  (platform setup/teardown, psa_crypto_init, threading-alt, debug hooks), so it
  *  drops into an integrator process that already uses Mbed TLS elsewhere. See
  *  docs/platforms/mbedtls/setup.md. */
@@ -40,13 +43,12 @@
 #include "SolidSyslogTlsHandshakeTimeoutFunction.h"
 
 struct SolidSyslogStream;
+struct SolidSyslogMbedTlsCredentials;
 
 /* Forward declarations keep the public header free of any mbedTLS include.
  * Integrators include the relevant mbedTLS headers themselves before this
- * one to bring the types into scope. See project_mbedtls_di_handles. */
+ * one to bring the types into scope. */
 struct mbedtls_ctr_drbg_context;
-struct mbedtls_x509_crt;
-struct mbedtls_pk_context;
 
 SOLIDSYSLOG_EXTERN_C_BEGIN
 
@@ -58,6 +60,13 @@ SOLIDSYSLOG_EXTERN_C_BEGIN
          *  destroys it; the caller owns it and must keep it valid until
          *  SolidSyslogMbedTlsStream_Destroy. */
         struct SolidSyslogStream* Transport;
+        /** Where the trust anchors, any pinned peer fingerprints and the mutual-TLS
+         *  client credential come from; required - a NULL is reported at
+         *  SolidSyslogMbedTlsStream_Create. Asked once per connection, so material
+         *  is fetched only for a connection actually being made, and told when the
+         *  connection ends. Borrowed - the caller owns it and must keep it valid
+         *  until SolidSyslogMbedTlsStream_Destroy. */
+        struct SolidSyslogMbedTlsCredentials* Credentials;
         SolidSyslogSleepFunction Sleep; /**< Bridges the WANT_READ/WANT_WRITE polls of the bounded handshake
                                              retry; required - a NULL is reported at
                                              SolidSyslogMbedTlsStream_Create. */
@@ -67,23 +76,18 @@ SOLIDSYSLOG_EXTERN_C_BEGIN
         struct mbedtls_ctr_drbg_context* Rng; /**< Seeded CTR-DRBG for the handshake; caller-built and caller-owned.
                                              Required - a NULL is reported at
                                              SolidSyslogMbedTlsStream_Create. */
-        struct mbedtls_x509_crt* CaChain; /**< Trust anchors the peer cert must chain to; caller-built and owned. */
         /** SNI + peer-identity check. A non-empty name is verified against the peer
          *  cert (SAN/CN). NULL connects chain-only but emits a WARNING - the peer is
          *  unverified (MITM-class). "" is the no-name-check opt-out (closed network /
-         *  private CA): the cert must still chain to CaChain, but the endpoint
-         *  identity is not checked; no diagnostic. */
+         *  private CA): the peer must still satisfy whatever the credentials
+         *  installed, but the endpoint identity is not checked; no diagnostic. */
         const char* ServerName;
-        struct mbedtls_x509_crt* ClientCertChain; /**< mTLS leaf (+ intermediates); caller-owned. NULL (or a NULL
-                                     ClientKey) disables mTLS - both must be set to present a client cert. */
-        struct mbedtls_pk_context* ClientKey; /**< Private key matching ClientCertChain; caller-owned. NULL disables
-                                     mTLS. */
     };
 
     /** Draw a TLS stream from the pool over the config's Transport (see the file
      *  overview for the handshake and I/O behaviour). A NULL config, a NULL
-     *  Transport, a NULL Sleep or a NULL Rng is reported and falls back to the
-     *  shared NullStream, as does an exhausted pool. */
+     *  Transport, a NULL Sleep, a NULL Rng or a NULL Credentials is reported and
+     *  falls back to the shared NullStream, as does an exhausted pool. */
     struct SolidSyslogStream* SolidSyslogMbedTlsStream_Create(const struct SolidSyslogMbedTlsStreamConfig* config);
     /** Release the pool slot; closes the TLS session and the underlying transport
      *  if the stream is still open. */

Platform/MbedTls/Interface/SolidSyslogMbedTlsStreamErrors.h

@@ -27,13 +27,12 @@ SOLIDSYSLOG_EXTERN_C_BEGIN
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_SERVER_NAME_NOT_SET,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_HANDSHAKE_REJECTED,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_HANDSHAKE_TIMEOUT,
-        SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_CLIENT_CREDENTIAL_INCOMPLETE,
-        SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_CLIENT_CREDENTIAL_MISMATCHED,
-        SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_CLIENT_CREDENTIAL_NOT_INSTALLED,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NULL_CONFIG,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NULL_TRANSPORT,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NULL_SLEEP,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NULL_RNG,
+        SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NULL_CREDENTIALS,
+        SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_NO_PEER_AUTHORISATION,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_PEER_CERTIFICATE_UNTRUSTED,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_PEER_NAME_MISMATCHED,
         SOLIDSYSLOG_MBEDTLS_STREAM_ERROR_PEER_CERTIFICATE_EXPIRED,