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)
• report which step of a failed TCP connect gave up (#865) (85af38d)
• S35.01 lwIP Sockets Address and Resolver (#886) (3f526b3)
• S35.02 lwIP Sockets Datagram and TcpStream (#887) (863aa3f)
• S35.03 run the BDD target's network through the lwIP Sockets API (#893) (33a733f)
• S36.01 a LittleFS File adapter (#877) (032d322)
• S36.03 run the BDD target's store on LittleFS (#881) (6174804)
• S39 authorise a TLS peer by certificate fingerprint (Core + OpenSSL) (#806) (f3e7445)
• S39 authorise a TLS peer by certificate fingerprint (Mbed TLS) (#808) (7bb982a)
• S39 detect a TLS configuration change from the stream (#809) (ebc17c9)
• S39 supply the TLS profile per connection, and bind cipher policy (#812) (804764e)
• S40.01 add the fourth BDD target and its lanes (#868) (bf0f792)
• S40.02 a CMSIS-RTOS2 Mutex (#871) (eed100c)
• S40.03 a CMSIS-RTOS2 uptime that survives its own tick rollover (#872) (7be7d51)
• S40.04 run the BDD target's OS primitives through CMSIS-RTOS2 (#876) (4da6840)
• the Mbed TLS stream asks a credentials source for its material (#802) (f9db5f5)
• the OpenSSL stream asks a credentials source for its material (#799) (c6720e3)

Bug Fixes

• carry FreeRTOS uptime past the tick counter's own rollover (#844) (bbff2b0)
• check the Mbed TLS client key against its certificate (#790) (05e8e68)
• check the wiring four Create functions cannot work without (#791) (35446ab)
• class-qualify the file-scope macros in the File adapters (#882) (cff8310)
• name the check that refused a TLS handshake (#792) (1201eb4)
• report a client credential a TLS stream cannot present, and keep delivering (#788) (c5c7e3f)
• report a mutual-TLS credential the Mbed TLS stream cannot present (#785) (0522448)
• report an unroutable destination as a connect that never started (#869) (c9f0e35)
• S39 stop a closed lwIP pcb reaching the stream that replaced it (#822) (20a1cce)
• S39.01 close the findings from the E39 closing security audit (#828) (4d07865)
• S39.01 name an allocation failure in the linked TLS library, and act on the integration field report (#831) (2878e46)
• S39.01 pin what the TLS adapters inherited, and rewrite the TLS docs (#829) (8cb0281)
• S39.04 report an address that does not match as a name mismatch, found by the TLS matrix (#821) (ff9f7c4)
• trim an over-large datagram on a platform that cannot name one (#841) (ee2365c)

Refactoring

• give every platform role one set of detail codes (#866) (8e8d3e4)
• give the TCP streams one set of detail codes (#863) (b612a1d)
• prefix the public error sources (#801) (047d94a)
• S39 give the crypto roles their detail codes from Core (#818) (5344bf7)
• S39 give the TLS-stream role one portable error enum (#814) (b6ef7a3)