From 90641126251b13d0d826b117ee2d8c9ec60f7649 Mon Sep 17 00:00:00 2001 From: David Cozens Date: Tue, 9 Jun 2026 09:20:35 +0000 Subject: [PATCH] docs: align RFC + IEC 62443 compliance docs with shipped features MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The compliance docs drifted from the implementation in three places: - IEC 62443 under-claimed at-rest crypto: E17 shipped mbedTLS AES-256-GCM (S17.04) alongside the OpenSSL variant, but CR 2.12 / CR 3.9 and the SL3/SL4 recipes only listed SolidSyslogOpenSslAesGcmPolicy. Now offers SolidSyslog{OpenSsl,MbedTls}AesGcmPolicy and reframes the E17 refs as shipped rather than in-progress. - IEC 62443 over-claimed SolidSyslogFormatter as an SL1 wiring component; S14.08 made the formatter library-private, so application code never touches it. Dropped from the SL1 recipe and CR 2.8. - RFC 5425 §4.1 omitted SolidSyslogLwipRawTcpStream (E28) from the list of TLS-capable byte transports; added it. Also updated the RFC 5424 §6.2.3 note to reference the public SolidSyslogHeaderField sink rather than the now-private formatter entry point. Co-Authored-By: Claude Opus 4.8 (1M context) --- docs/iec62443.md | 13 ++++++------- docs/rfc-compliance.md | 4 ++-- 2 files changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/iec62443.md b/docs/iec62443.md index dcb16584..e5f7ef4f 100644 --- a/docs/iec62443.md +++ b/docs/iec62443.md @@ -31,12 +31,12 @@ at the end of this document for recommended starter component sets. |---|---|---|---|---| | CR 1.5 | Authenticator management | SL4 | `SolidSyslogTlsStream` mTLS — caller supplies `clientCertChainPath` / `clientKeyPath`; `SSL_CTX_check_private_key` validates the key/cert pair before any bytes hit the wire. Rotation by file replacement plus reconnect (natural reconnect or explicit `SolidSyslogSender_Disconnect`) | Library ships no default authenticators; at-rest key protection (filesystem permissions, HSM) is the integrator's responsibility | | CR 1.8 | Public key infrastructure certificates | SL4 | `SolidSyslogTlsStream` — `caBundlePath` loads trust anchors via `SSL_CTX_load_verify_locations`; `SSL_VERIFY_PEER` pinned on the CTX; hostname verification via `SSL_set1_host`. CTX rebuilt on every `Open` so file replacement + reconnect refreshes trust anchors | Revocation (CRL / OCSP) deferred to the OS trust store per [S03.08 ADR](https://github.com/DavidCozens/solid-syslog/issues/172); enrolment is the caller's PKI process | -| CR 2.8 | Auditable events | SL1+ | `SolidSyslog_Log` formats events per RFC 5424 via `SolidSyslogFormatter`. Structured data attached via `SolidSyslogMetaSd` / `SolidSyslogTimeQualitySd` / `SolidSyslogOriginSd`, or caller-supplied SD. Application defines what to log | None | +| CR 2.8 | Auditable events | SL1+ | `SolidSyslog_Log` formats events per RFC 5424. Structured data attached via `SolidSyslogMetaSd` / `SolidSyslogTimeQualitySd` / `SolidSyslogOriginSd`, or caller-supplied SD. Application defines what to log | None | | CR 2.9 | Audit storage capacity | SL2+ | `SolidSyslogBlockStore` — rotating blocks, configurable `max-blocks` and `max-block-size`, configurable discard policy (`oldest` / `newest` / `halt`). Backed by `SolidSyslogFileBlockDevice` over `SolidSyslogPosixFile` (POSIX) or `SolidSyslogWindowsFile` (Windows). Size to the deployment's outage budget. Configurable early-warning threshold via `SolidSyslogStoreThresholdFunction` + `SolidSyslogStoreThresholdCallback` — edge-triggered, fires once when used-bytes crosses the threshold, re-arms when usage falls back below | None | | CR 2.10 | Response to audit processing failures | SL3+ | `SolidSyslogStoreFullCallback` (halt policy) and the discard-policy enum. Caller picks the policy that fits the deployment's audit-loss tolerance. The early-warning threshold callback (CR 2.9) fires *before* discard / halt engages, giving the application time to act (notify operator, reduce verbosity, tighten retention); at 100% with HALT both fire on the same Write with threshold first then `onStoreFull` | None | | CR 2.11 | Timestamps | SL1+ | Caller-injected `SolidSyslogClockFunction` — `SolidSyslogPosixClock_GetTimestamp` (POSIX) or `SolidSyslogWindowsClock_GetTimestamp` (Windows). Quality metadata via `SolidSyslogTimeQualitySd` (`tzKnown` / `isSynced` / `syncAccuracy`) | None | -| CR 2.12 | Non-repudiation | SL3+ | At the wire: `SolidSyslogTlsStream` mTLS cryptographically identifies the sender (SL4 deployments). End-to-end loss detection: `SolidSyslogMetaSd` sequenceId, gap detection at the SIEM. At rest: cryptographic integrity via `SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy`, or authenticated encryption via `SolidSyslogOpenSslAesGcmPolicy` ([E17 #105](https://github.com/DavidCozens/solid-syslog/issues/105)); `SolidSyslogCrc16Policy` remains for accidental-corruption detection | Cryptographic at-rest policies are keyed — key custody, rotation, and tamper-evident storage are integrator responsibilities. See [at-rest cryptography](security/at-rest-cryptography.md) | -| CR 3.9 | Audit information protection | SL2+ | In transit: `SolidSyslogTlsStream` (TLS 1.2+, AEAD ciphers, hostname verification, optional mTLS). At rest: cryptographic integrity (HMAC-SHA256) or authenticated encryption (AES-256-GCM, `SolidSyslogOpenSslAesGcmPolicy`); `SolidSyslogCrc16Policy` for accidental-corruption detection. See [at-rest cryptography](security/at-rest-cryptography.md) | At-rest key management is the integrator's responsibility | +| CR 2.12 | Non-repudiation | SL3+ | At the wire: `SolidSyslogTlsStream` mTLS cryptographically identifies the sender (SL4 deployments). End-to-end loss detection: `SolidSyslogMetaSd` sequenceId, gap detection at the SIEM. At rest: cryptographic integrity via `SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy`, or authenticated encryption via `SolidSyslog{OpenSsl,MbedTls}AesGcmPolicy` (shipped under [E17 #105](https://github.com/DavidCozens/solid-syslog/issues/105)); `SolidSyslogCrc16Policy` remains for accidental-corruption detection | Cryptographic at-rest policies are keyed — key custody, rotation, and tamper-evident storage are integrator responsibilities. See [at-rest cryptography](security/at-rest-cryptography.md) | +| CR 3.9 | Audit information protection | SL2+ | In transit: `SolidSyslogTlsStream` (TLS 1.2+, AEAD ciphers, hostname verification, optional mTLS). At rest: cryptographic integrity (HMAC-SHA256, `SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy`) or authenticated encryption (AES-256-GCM, `SolidSyslog{OpenSsl,MbedTls}AesGcmPolicy`); `SolidSyslogCrc16Policy` for accidental-corruption detection. See [at-rest cryptography](security/at-rest-cryptography.md) | At-rest key management is the integrator's responsibility | | SR 6.1 | Audit log accessibility | SL1+ | Two wirings, two cost models. **Single-task (`SolidSyslogPassthroughBuffer`):** `SolidSyslog_Log` performs the transport `Send` synchronously on the caller's thread. The TCP socket is non-blocking from the moment it is opened (see [`SolidSyslogPosixTcpStream.c`](../Platform/Posix/Source/SolidSyslogPosixTcpStream.c) and [`SolidSyslogWinsockTcpStream.c`](../Platform/Windows/Source/SolidSyslogWinsockTcpStream.c)), so `Send` returns immediately on a wedged peer or a full kernel buffer; the bounded blocking surface is the initial `connect()`, sized by `SOLIDSYSLOG_TCP_CONNECT_TIMEOUT_MS` (default 200 ms) or runtime-overridable per Stream via `GetConnectTimeoutMs(ConnectTimeoutContext)` ([S12.17 #282](https://github.com/DavidCozens/solid-syslog/issues/282)). On the TLS path the same applies to the handshake — `SOLIDSYSLOG_TLS_HANDSHAKE_TIMEOUT_MS` (default 5000 ms) or `GetHandshakeTimeoutMs(HandshakeTimeoutContext)` for both OpenSSL and Mbed TLS adapters. Long-term silent peer death is detected out-of-band via kernel `TCP_KEEPALIVE` + `TCP_USER_TIMEOUT`. Suitable when the application has no real-time deadline or the transport latency is known to be sub-millisecond. **Buffered (`SolidSyslogCircularBuffer` with an injected `SolidSyslogMutex` — Posix / Windows / FreeRTOS / Null / caller-supplied RTOS primitive — or `SolidSyslogPosixMessageQueueBuffer`):** `SolidSyslog_Log` is non-blocking — it formats and enqueues, returning before any I/O. `SolidSyslog_Service`, called on the integrator's chosen thread (typically a dedicated service thread), performs the transport I/O against the same non-blocking socket; the bounded surface is the same connect / handshake budget as the single-task wiring. Caller picks the wiring that fits the deployment's audit-loss / latency trade-off | None | | SR 6.2 | Continuous monitoring | SL2+ | TCP / TLS delivery confirmation via `SolidSyslogStreamSender`. Replay across outages via `SolidSyslogBlockStore` store-and-forward. SIEM-side gap detection via `SolidSyslogMetaSd` sequenceId | None | @@ -221,8 +221,7 @@ above for the canonical CR-to-component mapping. ### SL1 — basic audit logging -- `SolidSyslog`, `SolidSyslogConfig` — core API. -- `SolidSyslogFormatter` — bounded buffer formatting. +- `SolidSyslog`, `SolidSyslogConfig` — core API. (RFC 5424 formatting is handled internally; the bounded-buffer formatter is library-private and needs no wiring.) - A clock — `SolidSyslogPosixClock_GetTimestamp` (POSIX) or `SolidSyslogWindowsClock_GetTimestamp` (Windows). - A sender — `SolidSyslogUdpSender` (RFC 5426 UDP) or `SolidSyslogStreamSender` over a TCP `Stream` (RFC 6587). - A buffer — `SolidSyslogPassthroughBuffer` (single-task), `SolidSyslogCircularBuffer` with a `SolidSyslogMutex` (cross-platform threaded — Posix / Windows / FreeRTOS / your RTOS primitive), or `SolidSyslogPosixMessageQueueBuffer` (POSIX `mqueue`). @@ -240,7 +239,7 @@ above for the canonical CR-to-component mapping. ### SL3 — adds non-repudiation and audit-failure response - All SL2 components. -- At-rest record protection (CR 2.12, CR 3.9): `SolidSyslogCrc16Policy` for accidental-corruption detection, or — where a local attacker is in scope — a keyed cryptographic policy (`SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy` for integrity, `SolidSyslogOpenSslAesGcmPolicy` for authenticated encryption). See [at-rest cryptography](security/at-rest-cryptography.md). +- At-rest record protection (CR 2.12, CR 3.9): `SolidSyslogCrc16Policy` for accidental-corruption detection, or — where a local attacker is in scope — a keyed cryptographic policy (`SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy` for integrity, `SolidSyslog{OpenSsl,MbedTls}AesGcmPolicy` for authenticated encryption). See [at-rest cryptography](security/at-rest-cryptography.md). - A discard-policy choice (`oldest` / `newest` / `halt`) and, if `halt` is selected, a `SolidSyslogStoreFullCallback` so the application can react when storage is exhausted (CR 2.10). - `SolidSyslogOriginSd` software / version metadata to identify the generating application. @@ -250,4 +249,4 @@ above for the canonical CR-to-component mapping. - `SolidSyslogTlsStream` (OpenSSL; POSIX / Windows) instead of plain TCP, configured with `caBundlePath`, `serverName`, and (for mutual-auth deployments) `clientCertChainPath` / `clientKeyPath` (CR 1.5, CR 1.8, CR 3.9 in transit). - Or, on embedded / FreeRTOS / bare-metal targets where OpenSSL is impractical, `SolidSyslogMbedTlsStream` (Mbed TLS) — same controls, dependency-injected handles rather than file paths. See [Embedded SL4](#embedded-sl4-solidsyslogmbedtlsstream) above and [`docs/integrating-mbedtls.md`](integrating-mbedtls.md) for the integrator guide. - A `cipherList` appropriate to the deployment's threat model — e.g. `"ECDHE+AESGCM:ECDHE+CHACHA20"` for TLS 1.2 AEAD with forward secrecy. On the Mbed TLS adapter the policy is owned by your Mbed TLS config; on the OpenSSL adapter it is owned by `SolidSyslogTlsStreamConfig`. -- Cryptographic at-rest protection ([E17 #105](https://github.com/DavidCozens/solid-syslog/issues/105)) closes the at-rest gap on CR 2.12 / CR 3.9: `SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy` for cryptographic integrity (SR 3.4), or `SolidSyslogOpenSslAesGcmPolicy` for authenticated encryption (SR 3.4 + SR 4.1). Key custody and rotation are integrator responsibilities — see [at-rest cryptography](security/at-rest-cryptography.md). +- Cryptographic at-rest protection ([E17 #105](https://github.com/DavidCozens/solid-syslog/issues/105)) closes the at-rest gap on CR 2.12 / CR 3.9: `SolidSyslog{OpenSsl,MbedTls}HmacSha256Policy` for cryptographic integrity (SR 3.4), or `SolidSyslog{OpenSsl,MbedTls}AesGcmPolicy` for authenticated encryption (SR 3.4 + SR 4.1). Key custody and rotation are integrator responsibilities — see [at-rest cryptography](security/at-rest-cryptography.md). diff --git a/docs/rfc-compliance.md b/docs/rfc-compliance.md index 8a234270..7a5920a1 100644 --- a/docs/rfc-compliance.md +++ b/docs/rfc-compliance.md @@ -18,7 +18,7 @@ Status key: | 6.2.1 | VERSION = 1 | Supported | | | 6.2.2 | TIMESTAMP — ISO 8601 with microseconds | Supported | 6-digit fractional seconds, UTC offset or `Z` | | 6.2.2 | TIMESTAMP — NILVALUE when clock unavailable | Supported | NilClock produces `-` | -| 6.2.3 | HOSTNAME — max 255 chars, PRINTUSASCII | Supported | Truncated to 255. Non-PRINTUSASCII bytes substituted with `?` via `SolidSyslogFormatter_PrintUsAsciiString` | +| 6.2.3 | HOSTNAME — max 255 chars, PRINTUSASCII | Supported | Truncated to 255. Non-PRINTUSASCII bytes substituted with `?`. Written through the public `SolidSyslogHeaderField` sink (`_PrintUsAscii`); the underlying formatter is library-private | | 6.2.4 | APP-NAME — max 48 chars, PRINTUSASCII | Supported | Truncated to 48. Non-PRINTUSASCII bytes substituted with `?` | | 6.2.5 | PROCID — max 128 chars, PRINTUSASCII | Supported | Truncated to 128. Non-PRINTUSASCII bytes substituted with `?` | | 6.2.6 | MSGID — max 32 chars, PRINTUSASCII | Supported | Truncated to 32. Non-PRINTUSASCII bytes substituted with `?` | @@ -62,7 +62,7 @@ The library ships two reference TLS adapters that satisfy this RFC: `SolidSyslog | Section | Requirement | Status | Notes | |---|---|---|---| -| 4.1 | TLS over TCP | Supported | `SolidSyslogTlsStream` (OpenSSL) or `SolidSyslogMbedTlsStream` (Mbed TLS) wraps a TCP `Stream` (`SolidSyslogPosixTcpStream` / `SolidSyslogWinsockTcpStream` / `SolidSyslogPlusTcpTcpStream` / caller-supplied) | +| 4.1 | TLS over TCP | Supported | `SolidSyslogTlsStream` (OpenSSL) or `SolidSyslogMbedTlsStream` (Mbed TLS) wraps a TCP `Stream` (`SolidSyslogPosixTcpStream` / `SolidSyslogWinsockTcpStream` / `SolidSyslogPlusTcpTcpStream` / `SolidSyslogLwipRawTcpStream` / caller-supplied) | | 4.2 | Default port 6514 | Supported | `SOLIDSYSLOG_TLS_DEFAULT_PORT` constant in `SolidSyslogTransport.h`, alongside the UDP and TCP defaults. Caller-supplied via the endpoint callback so multi-port deployments can override | | 5.1 | Server certificate validation | Supported | OpenSSL adapter: `SSL_VERIFY_PEER` + `SSL_CTX_load_verify_locations` + `SSL_set1_host`. Mbed TLS adapter: `MBEDTLS_SSL_VERIFY_REQUIRED` + `mbedtls_ssl_conf_ca_chain` against the caller's `mbedtls_x509_crt*` + `mbedtls_ssl_set_hostname` | | 5.2 | Mutual TLS (client certificate) | Supported | OpenSSL: optional `clientCertChainPath` / `clientKeyPath` on `SolidSyslogTlsStreamConfig`; `SSL_CTX_check_private_key` confirms pairing. Mbed TLS: optional `ClientCertChain` / `ClientKey` handles on `SolidSyslogMbedTlsStreamConfig`; `mbedtls_ssl_conf_own_cert` |