tests/api is one binary compiled in every CI configuration, so a test calling
an API the build did not compile is not a test failure -- it is a link error
that takes the whole binary down. It is also invisible to header inspection,
because wolfSSL declares plenty of API unconditionally and implements it under
a narrower condition. That combination broke CI four separate times on this
branch, each time found by CI rather than locally, and each time the fix was
the same: name what the build provides, not what the test needs.
check-api-guards.py walks the enclosing #if chain of every call site and
requires the macros the IMPLEMENTATION carries. It is a whitelist rather than
a parse of ssl.h on purpose: the mapping from symbol to implementation guard
cannot be derived from the declaration, which is the whole problem.
Two things make it usable rather than noisy:
It only looks at call sites this branch changed. Run over everything it
reports 28 long-standing sites that are fine in practice because the
configurations that would break them are not built; auditing those is a
different job, and --all still does it.
It knows which macros imply TLS. A block under WOLFSSL_TLS13 or HAVE_SNI
cannot also need !defined(NO_TLS) spelled out, and comments and string
literals are blanked before matching, since these files discuss the very
API names being searched for.
It refuses to run against a ref it cannot resolve rather than reporting
success, because a shallow checkout would otherwise make every diff empty and
the check would pass without looking at anything. The workflow checks out with
fetch-depth: 0 for that reason, and runs the check before the smoke build --
it needs no build and costs a second.
Verified both directions: clean on this branch, and it reports the exact site
when !defined(NO_TLS) is removed from a guard that needs it.
A hardware key store holds keys with a lifetime of their own, and none of the
existing callbacks can manage them. WC_ALGO_TYPE_SETKEY and
WC_ALGO_TYPE_EXPORT_KEY are bound to a wolfCrypt key object and carry material
for that object's own use: neither can name a stored key, ask for one to be
created exportable, or make one outlive the object that used it. Wrapped keys
add a second reason, since a wrapped blob never becomes plaintext on this side
of the boundary at all.
Add a dedicated algorithm type covering the operations that manage a stored
key, whether or not they cross that boundary:
WC_KEYSTORE_IMPORT_PLAIN place plaintext key material into a slot
WC_KEYSTORE_EXPORT_PLAIN read a stored key back as plaintext
WC_KEYSTORE_IMPORT_WRAPPED unwrap a blob directly into a slot
WC_KEYSTORE_EXPORT_WRAPPED wrap a stored key back out
WC_KEYSTORE_DERIVE derive slot to slot without touching RAM
WC_KEYSTORE_DELETE destroy a stored key
WC_KEYSTORE_GET_INFO query what a slot holds
The plaintext pair is what most key stores outside the secure-element class
offer, and it is the shape wc_Pkcs11StoreKey() already implements privately:
that function takes a Pkcs11Token* rather than a devId, so an application using
it is bound to PKCS#11 even though the operation is generic. Devices that hold
keys which may never appear in plaintext decline the pair and offer only the
wrapped form.
Delete is deliberately separate from WC_ALGO_TYPE_FREE: freeing a wolfCrypt key
object must never destroy the hardware key it refers to.
A key reference is not a new naming scheme. It is the identifier
WOLF_PRIVATE_KEY_ID already uses, so the bytes that name a key here are the
bytes wc_ecc_init_id() or wc_AesInit_Id() take to bind an object to that key,
and the bytes read back from key->id afterwards. wolfCrypt copies them through
without inspection.
Two details come from building the NXP EdgeLock port against this surface,
which is what a design like this needs before it is fixed in place.
Every operation that creates a key takes keyType, because a key store has to
know what a key is for before it can set its permissions, and the material
does not always say. Raw bytes carry no metadata, and neither does a bare
RFC 3394 wrap, which is a pure data transformation. A vendor container that
carries its own property word stays authoritative over what it holds and
keyType is then a cross-check, which catches the right blob going into the
wrong kind of slot; a device must refuse a mismatch rather than silently
prefer one source. WC_KEYSTORE_KEY_NONE leaves the choice to the device. The
export operations take no keyType, since the key already exists and GET_INFO
reports it.
attrs travels with every creating operation for the same reason, but as a
source only. A format carrying no attributes of its own leaves attrs as the
device's only word on what the new key may do. A container that carries them
wins and attrs is ignored, and it cannot usefully be cross-checked there:
a container's attributes are inside the wrap and are not known until the key
exists, whereas keyType is checkable up front against the reference being
imported into. wc_KeyStore_GetInfo() is how a caller confirms what an import
produced.
keyType also fixes how plaintext material is encoded, so no further argument
is needed to say. A symmetric type takes the raw key bytes; an asymmetric type
takes DER, a private key as PKCS#8 PrivateKeyInfo and a public key as
SubjectPublicKeyInfo. Stating it matters: WC_KEYSTORE_KEY_ECC_SIGN and a byte
string do not otherwise say whether the bytes are a scalar, SEC1 or PKCS#8,
and two devices could each pick differently and both be defensible.
Keys that act on other keys need naming. Without WC_KEYSTORE_KEY_WRAP and
WC_KEYSTORE_KEY_DERIVE a device asked about a wrapping key can only answer
NONE, which is indistinguishable from an empty slot and defeats the point of
GET_INFO. Measured on hardware, a 256-bit wrapping key reported type 0 with
256 bits, which tells a caller nothing about what it may do with it. Both are
listed ahead of the algorithm types, since they name what a key acts on rather
than which algorithm it serves.
The algorithm types cover what the two other backends this was checked against
actually store. wc_Pkcs11StoreKey() handles RSA, ECC and ML-KEM today, and
wolfHSM's WH_KEY_ALGO_ENUM names RSA, ECC, Curve25519, Ed25519, ML-DSA, ML-KEM,
LMS and XMSS, so a shorter vocabulary would have left the facility unusable to
both for anything but symmetric keys.
An algorithm serving two purposes a key store grants separately is split, since
one key doing both is the key-separation problem and a caller has to be able to
ask for the narrower key. RSA and ECC are the only two: PKCS#11 carries
CKA_SIGN and CKA_DECRYPT independently for RSA, and CKA_SIGN against CKA_DERIVE
for ECC. wolfCrypt's own PKCS#11 layer honours that for ECC, selecting from the
ecc_key flags, but sets both CKA_DECRYPT and CKA_SIGN unconditionally for RSA
because no equivalent RsaKey flag exists; expressing the distinction here is
what would let that be tightened later. The remaining types serve one purpose
each and are not split. Signature use is listed before agreement or transport
use throughout.
Argument order follows one rule: two interchangeable control words are never
left adjacent, because a transposition between them compiles cleanly and
surfaces much later as an unrelated-looking failure. An earlier arrangement had
attrs and kdfType separated only by a pointer and a length, and swapping them
silently created a key without the exportable attribute, whose export then
failed two operations away from the mistake. Beyond that each control word sits
beside what it describes. wc_KeyStore_ImportPlain is the one place the two aims
collide and the first wins: attrs sits at the tail of every creating operation
rather than beside keyType, because WC_KEYSTORE_ATTR_EXPORTABLE and
WC_KEYSTORE_KEY_WRAP are both 1 and a swap would be silent. All three creating
operations therefore read keyRef, keyRefSz, keyType, then what they draw the
key from, then attrs.
kdfType refers to enum wc_KdfType, and WC_KDF_TYPE_NONE asks for the device's
own derivation, which is all many key stores offer.
Attributes are fixed when a key is created; hardware generally burns them in,
so there is no operation here to change them afterwards. They round-trip: a
device that can represent one must report it back through GET_INFO, so a caller
can ask whether an export is permitted rather than attempting one and
interpreting the error. Attributes the device cannot represent read as absent,
and out parameters it does not fill are cleared rather than left holding the
caller's stack.
Gated behind WOLF_CRYPTO_CB_KEYSTORE, with tests in wolfcrypt/test and
tests/api that assert each operation reaches the device carrying the arguments
the caller passed, not merely that the call returned zero.
Argument guards of wc_Compress_ex, wc_DeCompress_ex and
wc_DeCompressDynamic, plus the inSz overflow cap. Takes compress.c to
8/8 with the existing compress_test() KAT.
Covers the argument guards of wc_FileLoad, wc_ReadDirFirst/Next,
wc_strtok, wc_strsep, wc_strlcpy's truncation arm and wolfSSL_NewThread.
wc_port.c had no test group of its own.
Builds clean under --enable-all, default and --enable-singlethreaded.
Clean up includes single return point from every function, consistent formatting function block comment and tests added.
ssl_api_rw.c: Cleanup; 6 helpers extracted from write_dup/shutdown; fixed a SendBuffered corner case that returned 0 instead of an error.
ssl_api_ext.c: Cleanup; extracted wolfssl_ticket_key_cb_process, wolfssl_rehandshake_prepare.
ssl_api_hs.c: Cleanup + de-indent; 9 helpers extracted, incl. shared wolfssl_handshake_flush/_done between connect and accept (~100 duplicated lines removed). wolfSSL_connect/accept left multi-exit.
ssl_api_cert.c: Cleanup of newer functions at end of file; extracted PushPeerCertToChain; fixed a double free in CreatePeerCertChain; fixed 5 wrong @param names.
ssl_api_crl_ocsp.c: Full cleanup of all 49 functions; wolfSSL_OCSP_parse_url rewritten; fixed a URL with no host returning success with the rest of the URL as the host; added IPv6 literal support; fixed 4 wrong WOLFSSL_ENTER names.
ssl.c: Moved the x509GetIssuerFromCM forward declaration here for clarity.
Add test_wc_WolfEventDecisionCoverage (group "wolfevent") driving the
wolfEvent / wolfEventQueue_* doubly-linked FIFO from the public API:
the queue==NULL || event==NULL guards (Push/Pop/Add/Remove, each operand
plus the all-false half), the Add first-element branch, the Remove
head/tail/sole cascade including the (event==head && event==tail) AND and
the defensive (next==NULL || prev==NULL) corruption guard, and the Poll
context-filter OR.
Guarded by HAVE_WOLF_EVENT (compiled empty otherwise). The queue core is
async-independent; it builds standalone (no WOLFSSL_ASYNC_CRYPT) now that
BUILD_WOLFEVENT is true under --enable-usersettings and wolfEvent_Poll no
longer warns on unused params in non-async builds.
A crypto callback that returns WC_PENDING_E for a TLS record cipher
silently corrupted records: Encrypt()/Decrypt() advance the cipher
state to CIPHER_STATE_END before the pending check, so on resume the
record is shipped without re-running the cipher.
WOLF_CRYPTO_CB_ASYNC_POLL gives crypto callback devices the QAT/Nitrox
"poll to fill output" completion model. On WC_PENDING_E the async event
stays queued; wolfSSL_AsyncPoll() re-enters the device with the new
WC_ALGO_TYPE_ASYNC_POLL (wc_CryptoCb_Poll) to finish the job and fill
the output buffer. The re-entry only polls while the event is still
pending, and a device that cannot complete the job (no poll support, or
it reports nothing pending) hard-fails with WC_HW_E rather than
reporting the op done with an unfilled buffer. Only the two async record
ciphers (AES and 3DES markers) are routed to poll completion, and only
when crypto callbacks are the async backend (not QAT/Cavium/SW);
handshake PK keeps the re-invoke model. The wolfSSL_AsyncPop eviction is
gated for poll-capable devices so the existing resume-at-CIPHER_STATE_END
path becomes correct with no record state-machine changes.
Without the feature (and without a software/QAT/Cavium backend) a
pending bulk cipher op now errors out with ASYNC_OP_E instead of
corrupting the record, and configure/cryptocb.c warn about the
unsupported combination.
Tests in tests/api/test_async.c cover direct AES-GCM/CBC/CCM and 3DES
poll completion in both directions at multiple pend depths, negative
cases for cipher types defined but not dispatched (ChaCha, single DES),
and full TLS 1.3 handshake+echo: an encrypt-offload run, a both-
directions run that offloads encrypt and decrypt on both peers using a
per-peer device, and the no-poll failure path.
Falcon had crypto-level coverage (KAT + native round-trip in
wolfcrypt/test/test.c) but, unlike ML-DSA and SLH-DSA, no dedicated
tests/api/ unit test exercising the public wc_falcon_* / wc_Falcon_* API
surface. This adds one, wired into the unit test runner as the "falcon"
group.
Coverage (both Falcon-512 / L1 and Falcon-1024 / L5, which are always
compiled together):
- sizes: size/priv_size/pub_size/sig_size vs the spec constants,
get_level round-trip, and NULL / unset-level rejection.
- make_key: NULL and unset-level rejection; real keygen -> check_key.
- sign_vfy: sign -> verify; wrong-message and one-byte tamper rejected;
too-small buffer -> BUFFER_E with the required length set;
verify with no public key -> BAD_FUNC_ARG.
- import_export: public / private-only (raw) / private (concat) / export_key
round-trips, each re-signed or verified, plus too-small
(BUFFER_E) and wrong-size (BAD_FUNC_ARG) paths.
- check_key: valid pass; corrupted public copy, public-only and
private-only keys all fail (PUBLIC_KEY_E); NULL rejected.
- der: KeyToDer / PrivateKeyToDer / PublicKeyToDer round-trips via
PrivateKeyDecode / PublicKeyDecode, size-query (NULL output),
and the SetAsymKeyDer too-small contract (BAD_FUNC_ARG).
- error_paths: exhaustive NULL / bad-level / wrong-size / no-key-set
argument sanitising for every public entry point.
Tests requiring key generation or signing are gated on
WC_FALCON_HAVE_NATIVE_SIGN so the file also builds in
WOLFSSL_FALCON_VERIFY_ONLY and WOLF_CRYPTO_CB_ONLY_FALCON configurations;
size and argument-sanitising tests run in every HAVE_FALCON build.
Verified: 7/7 pass under both --enable-falcon-avx2 and the default
constant-time build; compiles clean with WOLFSSL_FALCON_VERIFY_ONLY.
Move out DTLS 1.3 specific tests into test_dtls13.c. (Also move out from
test_dtls.c)
Move out DTLS tests into test_dtls.c.
Move out LMS and XMSS tests into test_lms_xmss.c.
Move out SSL session tests into test_session.c.
Move out remaining ML-DSA/Dilithium tests in api.c into test_mldsa.c.
EVP into test_evp_cipher, test_evp_digest, test_evp_pkey and test_evp.
OBJ into test_ossl_obj.
OpenSSL RAND into test_ossl_rand.
OpenSSL PKCS7 and PKCS12 tests into test_ossl_p7p12.
CertificateManager into test_certman.
Move some BIO tests from api.c into test_evp_bio.c.
Fix line lengths.
General stack APIs pulled out into ssl_sk.c.
Other simple APIs also pulled out into ssl_sk.c.
wolfSSL_lh_retrieve also pulled out into ssl_sk.c.
Added tests of public APIs that weren't already tested.
Improved testing of random APIs.
wolfmath tests moved out.
Public key algorithm testing moved out: RSA, DSA, DH, ECC, SM2,
Curve25519, Ed25519, Curve448, Ed448, ML-DSA.
Signature API tests moved out.
Fix for OCSP testing to ensure RSA is available.
Added group names to API test cases.
Can select groups to run with --group <name>. --groups lists all known
group names.
Added option to stop API testing on first failure: --stopOnFail.
Make testing digests consistent.
Add KATs for all digests.
Check unaligned input and output works.
Perform chunking tests for all digests.
Fix Blake2b and Blake2s to checkout parameters in update and final
functions.
Fix Shake256 and Shake128 to checkout parameters in absorb and squeeze
blocks functions.
Add default digest size enums for Blake2b and Blake2s.
ML-KEM/Kyber:
MakeKey call generate random once only for all data.
Allow MakeKey/Encapsulate/Decapsulate to be compiled separately.
Pull out public key decoding common to public and private key decode.
Put references to FIPS 140-3 into code. Rename variables to match FIPS
140-3.
Fix InvNTT assembly code for x64 - more reductions.
Split out ML-KEM/Kyber tests from api.c.
TLSX:
Store the object instead of the private key when WOLFSSL_MLKEM_CACHE_A
is defined or WOLFSSL_TLSX_PQC_MLKEM_STORE_OBJ. Faster decapsulation
when A is cached and object stored.
To store private key as normal define
WOLFSSL_TLSX_PQC_MLKEM_STORE_PRIV_KEY.
misc.c: when Intel x64 build, assume able to read/write unaligned
