wolfSSL¶
Platform/WolfSsl/ wraps wolfSSL for embedded
targets: TLS over an injected transport, filling the
Stream role, and keyed at-rest
cryptography over wolfCrypt, filling the
SecurityPolicy role.
This page covers what this adapter needs, which of your wolfSSL build's choices it depends on, how it meets the TLS obligations, where it falls short of them, and the coexistence guarantee it makes.
What it ships¶
| Header | What it is |
|---|---|
SolidSyslogWolfSslAesGcmPolicy.h |
AES-256-GCM confidentiality-and-integrity SecurityPolicy via wolfCrypt, for a store that must encrypt records at rest. |
SolidSyslogWolfSslAesGcmPolicyErrors.h |
Source identity for the WolfSslAesGcmPolicy adapter; the detail codes it reports are the portable ones in SolidSyslogAesGcmPolicyErrors.h. |
SolidSyslogWolfSslCredentialsDefinition.h |
The wolfSSL credentials vtable (Install / Release) - where a TLS stream's trust anchors, client credential and pinned peer fingerprints come from, and the extension point an implementor fills in. |
SolidSyslogWolfSslHmacSha256Policy.h |
HMAC-SHA256 integrity SecurityPolicy via wolfCrypt, for a store that must detect tampering of records at rest (authentication only, no confidentiality). |
SolidSyslogWolfSslHmacSha256PolicyErrors.h |
Source identity for the WolfSslHmacSha256Policy adapter; the detail codes it reports are the portable ones in SolidSyslogHmacSha256PolicyErrors.h. |
SolidSyslogWolfSslNullCredentials.h |
The no-op wolfSSL credentials Null object: installs nothing and releases nothing. |
SolidSyslogWolfSslPemBufferCredentials.h |
The wolfSSL credentials backend that loads PEM from caller-owned buffers: trust anchors, an optional client credential for mutual TLS, and the pinned peer fingerprints the stream reads. |
SolidSyslogWolfSslPemBufferCredentialsErrors.h |
Source identity for the WolfSslPemBufferCredentials adapter; the detail codes it reports are the portable ones in SolidSyslogTlsCredentialsErrors.h. |
SolidSyslogWolfSslStream.h |
TLS over an injected byte-transport Stream via wolfSSL, itself a Stream - so a StreamSender speaks TLS to a remote collector without knowing the transport underneath, whether a TCP stream from a platform pack or one the caller supplies. |
SolidSyslogWolfSslStreamErrors.h |
Source identity for the WolfSslStream adapter; the detail codes it reports are the portable ones in SolidSyslogTlsStreamErrors.h. |
Requirements¶
The adapter sources compile in your target against your own wolfSSL build. A
./configure build describes itself in wolfssl/options.h, and the adapter
includes it; a user_settings.h build defines WOLFSSL_USER_SETTINGS, and the
adapter reads that file through wolfSSL's own settings.h instead. Either way
the features your build enables are the features it gets, and the adapter asks
for no configure flag.
wolfSSL 5.7.0 or later: the stream's pin digest calls wc_Hash_ex, which
earlier releases do not have. The pack is tested against 5.9.4 on both routes
in CI.
As a ./configure build it runs twice: once against a build with the options it
asks for, and once against a bare ./configure, so it is known to compile,
link and work on the build an integrator has rather than only on the one it
prefers. As a user_settings.h build it runs on an embedded target, with
wolfSSL compiled from source into the image, static memory and no filesystem.
The build choices that change what it does are listed below.
wolfSSL is dual-licensed, GPLv3 or commercial, since 5.8.2; earlier releases were GPLv2. SolidSyslog links your build and ships none of it, so the licence choice stays with you.
wolfSSL_Init is yours to call, once, before the first connection, and
wolfSSL_Cleanup yours to call after the last; the stream calls neither, as
the coexistence contract below says. No random number generator is handed to
the stream: wolfSSL seeds its own from your build's seed source.
An initialised WC_RNG is required by the AES-GCM policy, for its nonces. The
HMAC policy needs none. wolfCrypt seeds the RNG from your build's seed source
when you initialise it, so seeding is not something this adapter can get wrong
or check.
Credentials come from a credentials source¶
Where trust anchors, pinned peer fingerprints and the mutual-TLS client
credential come from is the integrator's choice rather than this adapter's. The
stream is wired to a SolidSyslogWolfSslCredentials, asked once per connection
to install its material on the WOLFSSL_CTX built for that connection and told
once per connection when that material is no longer needed. A source backed by
a secure element or a key store is a class implementing that role, and needs no
change here.
One source ships with the pack, and it opens no file - which is what allows the
adapter to run on targets built with NO_FILESYSTEM.
SolidSyslogWolfSslPemBufferCredentials carries PEM held in memory and hands it
to wolfSSL per connection. Nothing is parsed at Create, and nothing is held
between connections: the material lives in the context the stream builds for a
connection, which the stream frees at Close. Because the source holds nothing of
its own, one instance can serve several streams at once, and rotating the
material is a matter of writing the new PEM over the buffer and moving the
stream's configuration version - the next connection reads the new bytes. Make
the change on the task that calls SolidSyslog_Service, so a connection never
reads a half-written buffer.
The credential window is explicit. Install is called after the transport connects and before the session is created, so what it installs is what the session inherits; Release answers every Install, once, after the context has been freed and with it every pointer into the material. That window is what a source reaching a secure element or an encrypted store needs.
A Release reached by destroying the stream runs inside the configuration lock,
because pool cleanup holds it. Freeing your own material there is fine; creating
or destroying any SolidSyslog object from Release is not, since that takes the
same lock and a non-recursive one deadlocks.
What it depends on in your build¶
The pack compiles against the builds below. What a choice costs is stated beside it; a choice the pack refuses is refused at build time, so the cost is never a silent one.
| Build choice | What the pack does with it |
|---|---|
HAVE_SNI (on in a ./configure build) |
Sends the expected peer name as the server name indication. Without it the indication cannot be set, and a connection that declares a name fails at Open as SERVER_NAME_NOT_APPLIED; a connection that declares none is unaffected |
WOLFSSL_IP_ALT_NAME (--enable-ip-alt-name) |
Matches an expected address literal against the certificate's iPAddress entries. Without it no address ever matches, and a peer expected by address is refused as PEER_NAME_MISMATCHED on every connection; expect the peer by name instead |
WOLFSSL_ALWAYS_VERIFY_CB, KEEP_PEER_CERT (define either) |
Decide how a pin is checked where trust anchors are installed too, below. With WOLFSSL_ALWAYS_VERIFY_CB it is checked in the verify callback, before the client's credential is sent. With only KEEP_PEER_CERT it is checked once the handshake has completed, against the certificate the library kept. With neither, anchors and pins together are refused at Open as PINS_WITH_ANCHORS_UNSUPPORTED; pins alone, and anchors alone, work on any build |
NO_SHA, NO_SHA256 |
Compile out the hash a pin names. A pin under a hash the build lacks is skipped, and a peer that no other pin names is refused as FINGERPRINT_DIGEST_UNAVAILABLE |
WOLFSSL_TLS13 (--enable-tls13, on in a ./configure build) |
Negotiates TLS 1.3 where the collector offers it. Without it the connection is TLS 1.2, which the floor permits |
NO_ASN_TIME |
Compiles the validity-period check out. The adapter will not build with it set, below |
RSA, finite-field Diffie-Hellman and ECC (NO_RSA, NO_DH, HAVE_ECC) |
The pack sets the key-size floor for all three, so a build that trims any of them out does not compile the stream. A trimmed build is not supported |
HAVE_AESGCM (on by default) |
The AES-GCM policy. A build without it has no wc_AesGcmEncrypt to link |
wc_ForceZero |
Wipes key material after every policy operation. A build that defines WOLFSSL_NO_FORCE_ZERO supplies its own, as wolfSSL documents |
One build is refused rather than used. --enable-afalg=xilinx and
--enable-afalg=xilinx-aes define WOLFSSL_AFALG_XILINX_AES, which routes
AES-GCM through the Linux AF_ALG interface to the Zynq accelerator. On that port
wc_AesGcmEncrypt and wc_AesGcmDecrypt read and write WC_AES_BLOCK_SIZE
bytes beyond the body they are given, as wolfSSL's API documentation for the two
functions states. The policy encrypts the record body in place, and the bytes
after it are the record's nonce and tag, so the port would overwrite them during
every seal. The pack therefore withholds
SolidSyslogWolfSslAesGcmPolicy_GcmEncrypt and
SolidSyslogWolfSslAesGcmPolicy_GcmDecrypt on that build, and the link fails
naming them, rather than sealing a record that could never be opened.
The padded versions are not written because there is no board here to run them
on. An integrator who has one supplies those two functions, declared in
SolidSyslogWolfSslAesGcmPolicyPrivate.h: copy the body into a buffer with
WC_AES_BLOCK_SIZE bytes of room after it, aligned to WOLFSSL_XILINX_ALIGN,
make the wolfCrypt call on that buffer with the nonce, tag and header arguments
the shipped versions pass, and copy the body back on success. The HMAC policy is
unaffected: the port takes nothing but AES.
Coexistence is an auditable contract¶
Platform/WolfSsl/Source/ calls no process-global wolfSSL API. It does not call
wolfSSL_Init or wolfSSL_Cleanup, install allocator or logging hooks, or
turn debugging on. TLS policy is applied per session, on a context built for
that one connection, so it cannot affect a context you build elsewhere. Every
wolfCrypt context the policies use is built for one operation and freed after
it. A device that already uses wolfSSL for firmware update or a vendor cloud
SDK keeps that configuration intact, and the claim can be checked against the
directory.
What it reports¶
Every class in this pack reports portable detail codes, so a handler written
against them keeps working if the crypto backend underneath changes. What stays
specific to this pack is event->Source, which names the class that reported.
Each role's codes are the whole vocabulary that role can express, so some describe faults this pack cannot have and it never raises them.
From the TLS-stream codes it does not raise NULL_RNG: no generator is handed
to the stream. HANDSHAKE_REJECTED covers what the peer or the protocol refused and no check
of this stream names, which includes a Diffie-Hellman group or a ciphersuite
below the floor.
From the credentials codes it does not raise NULL_RNG or ALREADY_IN_USE:
the PEM-buffer source needs no generator, and holds nothing between
connections, so it is never in use. Nor PEM_NOT_TERMINATED: wolfSSL reads a buffer to the
length it is given and needs no terminator. Nor TRUST_ANCHORS_NOT_LOADED: the
source parses a buffer and reports TRUST_ANCHORS_NOT_PARSED if that fails.
Nor CLIENT_CREDENTIAL_MISMATCHED: whether a client key matches its
certificate is not checked, because the only wolfSSL call that checks it lives
in the compatibility layer wolfSSL offers for another library's API, which this
pack never enables. A mismatch surfaces when the collector refuses the
handshake.
The at-rest policies raise every code their roles define.
What a connection is made with¶
The stream asks for a profile once per connection, and takes the expected peer name and the cipher policy from it. Nothing is stored between connections, so a change is a matter of returning something different and moving the stream's version.
A name is validated by wolfSSL as a hostname when it is declared: labels of
letters, digits and hyphens, at least two of them, the last not all digits.
localhost is accepted as itself. A name wolfSSL will not take - a single
label, a wildcard, a leading dot - fails the connection at Open as
SERVER_NAME_NOT_APPLIED, which names the configuration rather than the peer.
A collector reached by a bare host name is declared by its fully qualified one.
A pinned peer needs no name. A pin declares the peer's identity more strongly than a name does, so a connection that pins the peer and declares no name is not reported as unnamed; one that declares a name still has it checked.
An expected identity that is an address literal - digits and dots, or anything
with a colon in it - is declared to wolfSSL as an address and matched against
the certificate's iPAddress entries alone, never against a DNS name or Common
Name spelling the same digits; RFC 9525 section 6.2 asks for exactly that. On a
build without WOLFSSL_IP_ALT_NAME nothing matches it, as the table above says.
The literal is sent as the server name indication as well, as the contract
requires of every declared name.
Of the cryptographic floor, the stream pins the protocol version at TLS 1.2 and
the key sizes BCP 195 section 4.5 names: 2048 bits for RSA and for finite-field
Diffie-Hellman, 224 bits for elliptic curves, applied to the peer's certificate
and to the handshake alike. A certificate whose key is below the floor is
refused as PEER_CERTIFICATE_UNTRUSTED, with the rest of what the chain fails
on. No ceiling is set: RFC 9662 requires TLS 1.3 to be preferred wherever it is
implemented, and a build with WOLFSSL_TLS13 negotiates it.
The cipher policy is one list for both TLS versions, in the form wolfSSL takes:
names separated by colons, each in wolfSSL's own spelling, such as
ECDHE-RSA-AES128-GCM-SHA256 and TLS13-AES128-GCM-SHA256, or in the IANA
one. A list that names a suite for each version is the whole of what is
offered, on any build. A list that names one version only offers nothing at the
other, except on a wolfSSL built with OPENSSL_EXTRA, which updates the
version the list names and keeps the other version's suites as they were. Name
a suite for each version to bind both.
Leave the policy unset and every suite the build enables is offered; an empty
list and the keywords ALL, DEFAULT and HIGH ask for the same. wolfSSL
keeps the names it knows and drops the rest without reporting them, so it
rejects a list only where it knows none of its names. That fails the connection
at Open as CIPHER_POLICY_REJECTED, before any handshake, and nothing is
widened to compensate. A suite the build knows and the collector will not
negotiate is refused in the handshake as HANDSHAKE_REJECTED. Key-exchange
groups and signature algorithms are not selectable through the list, and the
key-size floors apply whatever it names.
Pinned peer fingerprints are read from the credentials source at each Open and
checked against the leaf the collector presents, by its SHA-256 or SHA-1 digest
as each pin names. A pin that will not parse fails the connection at Open as
FINGERPRINT_MALFORMED, and a sha-1 pin is reported as FINGERPRINT_SHA1 on
every connection that uses one.
With pins and no trust anchors, every chain fails wolfSSL's verification for
want of a signer, and that is the one objection a matching pin waives. A
collector with no PKI is authorised by its pin alone, whether it presents a
self-signed certificate or one with its issuer behind it. wolfSSL stops at the
missing signer and reports nothing it found before it, so the stream checks
what would otherwise go unchecked: each certificate whose missing signer it
waives is parsed again as a trust anchor would be, and one outside its validity
period is refused as PEER_CERTIFICATE_EXPIRED or
PEER_CERTIFICATE_NOT_YET_VALID, as the contract requires of a pin. A name that
does not match, and a key below the floor, are refused as they would be without
a pin.
With pins and trust anchors both installed, the peer must chain to an anchor
and match a pin. How the pin is checked on a chain that verifies depends on the
build, as the table above says: wolfSSL calls the verify callback on a
certificate that verifies only under WOLFSSL_ALWAYS_VERIFY_CB. A build may
choose a weaker check than its flags allow by defining
SOLIDSYSLOG_WOLFSSL_ANCHORED_PIN_CHECK to
SOLIDSYSLOG_WOLFSSL_ANCHORED_PIN_CHECK_AFTER_HANDSHAKE or
SOLIDSYSLOG_WOLFSSL_ANCHORED_PIN_CHECK_REFUSED - the refusal, say, rather than a
check made after the client credential has gone. A choice the flags cannot
honour stops the build.
Each connection is a fresh session with none supplied to resume, and the stream never enables early data or renegotiation, so it meets the contract's resumption and early-data obligations by construction.
A send first reads what the collector has sent, so that a session the collector has closed refuses the record rather than taking it, as the Stream contract requires. A write alone would not notice: wolfSSL takes the record into the session regardless of the close_notify waiting unread, and the transport beneath may not see the collector's close behind that unread alert. When the read meets the close, or the transport has gone, the send fails, the stream closes itself, and your store replays the record on the next connection. Syslog over TLS carries nothing from collector to device, so the read normally finds nothing; application data it does meet is discarded, not kept for a later read, and the probe makes at most eight reads of up to 16 bytes each, so a close behind more than that goes unnoticed.
A client credential supplied to the PEM-buffer source is loaded onto the context and presented when the collector asks for one.
Where it falls short of the contract¶
Certificate validity is checked only where the build carries a clock, below.
On a build with KEEP_PEER_CERT and without WOLFSSL_ALWAYS_VERIFY_CB, a pin
beside trust anchors is checked once the handshake has completed, so a collector
whose chain verifies and whose certificate matches no pin is refused after the
device has sent its client credential, where one is configured. No record is
sent to it. Build with WOLFSSL_ALWAYS_VERIFY_CB to refuse it first.
Of the cryptographic floor, what a certificate in the chain may be signed with is not pinned. wolfSSL offers no per-connection way to refuse a chain certificate signed with SHA-1; the only control is building the library without SHA-1 at all, which refuses it everywhere. A deployment that must refuse such a chain builds wolfSSL that way, or issues its collector certificates without one.
Every other obligation under TLS obligations is met by this pack as shipped.
Certificate validity depends on your build carrying a clock¶
NO_ASN_TIME is what makes wolfSSL skip the dates on a certificate. With it set
the expired and not-yet-valid checks are compiled out, and a certificate outside
its validity period is accepted - silently, because nothing failed. On a board
with no real-time clock it is tempting to set it for exactly that reason, and
doing so gives up the last time-based control the contract has.
The adapter will not build with it set. A target that genuinely has no clock
defines SOLIDSYSLOG_WOLFSSL_NO_VALIDITY_CHECK to say so, which builds and
leaves the obligation knowingly unmet rather than quietly missing. Nothing
reports this at runtime, because by then there is nothing left to detect it
with - which is why the decision is forced at build time instead.
Without NO_ASN_TIME, wolfSSL reads the clock through XTIME, which is libc
time() unless your build says otherwise with USER_TIME and a definition of
its own. A newlib toolchain links time() against a stub that returns -1, and
wolfSSL then reads every certificate as outside its validity period - so a peer
that is plainly current is refused as not yet valid. The build will not tell
you; supply the clock. A coarse one is enough: X.509 asks only which side of a
window the device is on.
USER_TIME is the smallest way to supply one. With it wolfSSL declares
time_t XTIME(time_t* timer) and calls it, so your build defines a function of
that name returning seconds since the Unix epoch, and wolfSSL converts the
result with a gmtime of its own. Where the toolchain already has time_t and
struct tm, define HAVE_TIME_T_TYPE and HAVE_TM_TYPE beside it and include
<time.h> from user_settings.h, or wolfSSL declares both types a second
time.