v0.2.0

This release, 0.2.0 is dominated by TLS, it lets a device authorise its collector by certificate
fingerprint, gives each TLS pack a credentials role of its own, and closes every
limitation 0.1.0 shipped with. It also adds three platform packs aimed at
microcontroller targets.

Still 0.x, for the reason 0.1.0 gave: the label describes platform breadth and
the absence of field integrations, not the maturity of the code. This release
does break the public API. Every break is listed below, under Before you
upgrade.

What's in this release

• Fingerprint pinning (RFC 5425 §5.1). A collector can be authorised by the
  fingerprint of its certificate, with no CA involved, so a closed site with no
  PKI can run TLS. More than one pin can be held at once, so a collector's
  certificate renewal can be crossed without stopping delivery. A CA chain can be required
  as well as the pin.
• A credentials role per TLS pack. The OpenSSL and Mbed TLS streams fetch
  their trust anchors, client credential and pins from a credentials source when
  they connect, and let go of them when the connection ends. A file, a
  caller-built handle, a secure element or a keyring can each back it.
• TLS policy per connection. The expected peer name, the cipher policy and,
  on Mbed TLS, the certificate profile are asked for at each connection. The
  cipher policy an integrator sets now binds the connection that is negotiated.
  A configuration change is picked up without a restart when the stream's
  version moves.
• Certificate validity is enforced by contract. A peer certificate outside
  its validity period stops delivery. 0.1.0 already behaved this way, but its
  contract said report and continue; the contract now says what the code does,
  and docs/tls.md gives the reasoning.
• One portable set of detail codes per role. A handler that matches on
  detail codes reacts the same way whichever backend raised the code.
• TCP. Keepalive timings are tunables shared by every TCP backend, and a
  failed connect reports which step gave up.
• An oversize datagram is trimmed on a platform that can only report a
  failure, not name the size.

Platforms added: lwIP Sockets API, CMSIS-RTOS2 (mutex and uptime), and
LittleFS. The full list is POSIX, Windows, C11 atomics, OpenSSL, Mbed TLS, lwIP
Raw API, lwIP Sockets API, FreeRTOS-Plus-TCP, FreeRTOS, CMSIS-RTOS2, ChaN FatFs,
FreeRTOS-Plus-FAT and LittleFS.

Before you upgrade

These break source compatibility with 0.1.0:

• Error enums by role. The per-pack SolidSyslog<Pack><Class>Errors enums
  for the Address, Datagram, Resolver, File, Mutex and AtomicCounter roles are
  replaced by SolidSyslog<Role>Errors, and their constants by
  SOLIDSYSLOG_<ROLE>_ERROR_*. The values are unchanged, so a handler matching
  on numbers is unaffected. The TCP streams, the TLS streams and the crypto
  roles each have one set of codes too.
• ErrorSource names. Every *ErrorSource object gains the SolidSyslog
  prefix: UdpSenderErrorSource becomes SolidSyslogUdpSenderErrorSource. A
  handler that matches on source identity must use the new names.
• TLS stream configuration. The OpenSSL and Mbed TLS streams take a
  credentials source instead of certificate and key fields, and take their peer
  name and cipher policy from a per-connection profile. The TLS setup pages show
  the new wiring.

Documentation corrected in this release, where acting on the old text would have
cost you:

• A consumer of the OpenSSL pack links OpenSSL::SSL OpenSSL::Crypto alongside
  SolidSyslog. The library does not link OpenSSL for you, and the docs said it
  did.
• A structured data element registered in SolidSyslogConfig.Sd[], and the
  array itself, must outlive the logger, not only the call that creates it.
• FreeRTOS-Plus-TCP needs ipconfigUSE_DNS=1 even when the collector is given as
  a numeric address.
• The POSIX pack needs Linux, not just a POSIX system.
• LittleFS has no usable default for block_cycles. Set it.
• A per-platform CMake switch such as -DSOLIDSYSLOG_LWIPRAW=ON takes effect
  only when SOLIDSYSLOG_PLATFORMS is Auto.
• A stored record that fails verification on read is discarded without a report,
  and shows at the collector as a gap in the sequence number. 0.1.0's IEC 62443
  and CRA pages said it was reported.

RFC compliance at this release

RFC	Total	Supported	Partial	Not Met	N/A
RFC 5424	40	33	0	0	7
RFC 5425	21	16	0	0	5
RFC 5426	16	7	0	0	9
RFC 6587	8	7	0	0	1

RFC 5425 is now met throughout.

• §5.1, authorising a peer by certificate fingerprint, moves from Not Met to
  Supported.
• §4.2.3 moves from Partial to Supported now that the cipher policy binds the
  connection, and gains a row for session resumption.

RFC 5426 has one row fewer because its two §3.2 rows are now one. No clause
changed status. RFC 5424 and RFC 6587 are unchanged.

The maintainer's assessment, not a certification. Each status describes the
library with a conforming platform supplying the roles it needs, and depends on
the components selected, including any you write yourself, which the library
cannot speak for. The full matrix at this release, one row and one note per
clause:
docs/rfc-compliance.md at v0.2.0.

Known limitations

Every limitation 0.1.0 shipped with is resolved in this release.

The pre-release audit of 0.2.0 read every documentation page against the code
again. Each finding is disclosed on the page for the affected platform, or in the
compliance guides:

• #919 - the OpenSSL
  stream reports an expired issuer ahead of a pin that matches nothing, where the
  contract puts the pin first. The peer is refused either way; only the reported
  code differs. Tracked for 0.3.0.
• #921 - a stored record
  that fails verification on read, and a failed store write on most file
  backends, reach no error handler. Tracked for 0.3.0.
• #842 - on an lwIP
  build with IPv6 enabled, the lwIP Raw API resolver accepts an IPv6 literal the
  datagram can never send to, so every send fails without saying why. Give the
  collector as an IPv4 address.

The Mbed TLS page also states three properties of Mbed TLS rather than of this
library:

• validity dates are checked only where the build carries a clock;
• an address literal can also match a DNS name spelling the same digits;
• the X.509 profile is the linked library's default unless CertProfile is set.

Verifying this release

Six assets are attached: the CycloneDX SBOM, the content-tree SHA-256, and the
offline documentation bundle, each with a cosign signature bundle. Signing is
keyless via GitHub OIDC, so each signature commits to the workflow run that
produced it. There is no personal key. The content-tree hash is reproducible from
any clone. Commands:
docs/security/release-verification.md at v0.2.0.
The check that matters is that a bundle verifies, not that the assets are
present.

The offline documentation bundle is new in this release: the documentation as
of this tag, readable with no server and no network.

Full changelog

⚠ BREAKING CHANGES

• the per-pack enums SolidSyslogErrors for the Address, Datagram, Resolver, File, Mutex and AtomicCounter roles are replaced by enum SolidSyslogErrors, and their SOLIDSYSLOG_ERROR* constants by SOLIDSYSLOGERROR*. The values are unchanged, so a handler matching on numbers is unaffected.
• give the TCP streams one set of detail codes (#863)
• S39 give the crypto roles their detail codes from Core (#818)
• S39 give the TLS-stream role one portable error enum (#814)
• S39 supply the TLS profile per connection, and bind cipher policy (#812)
• the Mbed TLS stream asks a credentials source for its material (#802)
• every *ErrorSource object declared in a public *Errors.h header gains the SolidSyslog prefix, so UdpSenderErrorSource becomes SolidSyslogUdpSenderErrorSource and the rest follow. An error handler that matches on source identity, event->Source == &UdpSenderErrorSource, must be updated to the new name. The matching rule itself is unchanged.
• the OpenSSL stream asks a credentials source for its material (#799)

Features

• a credentials role for each TLS pack (#797) (7e446d0)
• an Mbed TLS credentials backend that parses PEM per connection (#803) (9ca9184)
• expose an optional Mbed TLS certificate profile (#908) (8f24d9b)
• give the TCP keepalive timings one set of tunables (#847) ([28dcdb2](28dcdb2918f22cfba8...

v0.1.0

First public release. SolidSyslog is a structured syslog client library for
embedded and industrial systems, built to give a shipping product the security
audit trail the EU Cyber Resilience Act and IEC 62443 expect. Everything in this
release is new; the generated change list begins at 0.2.0.

Released as 0.x deliberately: the beta label describes the breadth of platform
coverage and the absence of field integrations to date, not the maturity of the
code. The public API changes before 1.0.0 only if integration feedback or a
security fix requires it.

What ships

• RFC 5424 structured formatting over UDP (RFC 5426), TCP (RFC 6587), and TLS
  or mutual TLS (RFC 5425)
• Asynchronous buffering and rotating block store-and-forward
• At-rest record protection: CRC-16 against accidental corruption, HMAC-SHA256
  for tamper evidence, AES-256-GCM for authenticated encryption
• C99, no dynamic allocation. Every instance lives in a static pool sized at
  compile time. Every platform dependency (network stack, TLS library,
  filesystem, OS primitives, clock) is injected behind a vtable; Core carries
  no reference to any of them. MISRA C:2012 informed
• Source only; there are no binary artefacts

Platforms: Posix, Windows, FreeRTOS, FreeRTOS-Plus-TCP, lwIP (Raw API),
OpenSSL, Mbed TLS, FatFs, FreeRTOS-Plus-FAT, C11 atomics.

RFC compliance at this release

RFC	Total	Supported	Partial	Not Met	N/A
RFC 5424	40	33	0	0	7
RFC 5425	20	13	1	1	5
RFC 5426	17	8	0	0	9
RFC 6587	8	7	0	0	1

The maintainer's assessment, not a certification. Each status describes the
library with a conforming platform supplying the roles it needs, and depends on
the components selected, including any you write yourself, which the library
cannot speak for. The full matrix at this release, one row and one note per
clause:
docs/rfc-compliance.md at v0.1.0.

Known limitations

Found by a pre-release audit that read every documentation page against the
code it describes. Each is disclosed where the reader meets it: on the page for
the platform it affects, or in the TLS contract and the compliance matrix. All
are tracked for 0.2.0.

TLS divergences from the contract in
docs/tls.md:

• #731 - an expired
  peer certificate stops delivery, where the contract says report and continue
• #732 - four
  <Class>_Create functions accept a configuration they cannot work without and
  report nothing
• #733 - the cipher
  policy an integrator sets does not bind the connection that is negotiated
• #734 - a
  half-supplied client credential stops delivery on the OpenSSL stream
• #718 - the Mbed TLS
  stream discards the mutual-TLS credential install result, allowing a silent
  downgrade to server-authenticated TLS
• #719 - the Mbed TLS
  stream does not validate the mutual-TLS key against its certificate
• #753 - a peer cannot
  yet be authorised by certificate fingerprint (RFC 5425 §5.1)

Transport:

• #736 - an oversize
  datagram is lost on a platform that cannot detect oversize. Not reachable at
  the default message size; it requires SOLIDSYSLOG_MAX_MESSAGE_SIZE raised
  above the payload the datagram reports
• #743 - TCP keepalive
  timings are file-scope constants rather than tunables, so dead-peer detection
  differs by two orders of magnitude across adapters
• #755 - FreeRTOS
  sysUpTime wraps early at tick rates that do not divide 100, including the
  1000 Hz default

The report-and-continue posture behind the TLS items is stated and argued in
docs/tls.md.
It is reasoned rather than field-tested, and 0.x is when integration feedback
can still change it cheaply.

Verifying this release

Four assets are attached: the CycloneDX SBOM, the content-tree SHA-256, and a
cosign signature bundle for each. Signing is keyless via GitHub OIDC, so each
signature commits to the workflow run that produced it. There is no personal
key. The content-tree hash is reproducible from any clone. Commands:
docs/security/release-verification.md at v0.1.0.
The check that matters is that a bundle verifies, not that the assets are
present.