3d683a35ec
Fix error-trace machinery and add missing WC_NO_ERR_TRACE()s: errno-domain
comparisons in the PK and SHA glue and module_hooks (ENOMEM, EAGAIN, EINTR,
EBADMSG, and wolfCrypt INTERRUPTED_E/NOT_READY_E sites) now use the
-WC_NO_ERR_TRACE(E*) idiom, with .wolfssl_known_macro_extras updated to match.
Change default kernel "mutex" (spinlock) behavior: atomic-context callers now
never spin -- they trylock and fail fast -- and task-context lockers re-enable
preemption (and with it, migration) immediately after acquisition, rebalancing
the preempt count just before release. The legacy behavior -- task-context
holders promoted to non-preemptible for the duration of the hold, permitting
atomic-context callers (except NMI) to spin-wait -- remains available via a new
WC_LINUXKM_SPIN_IN_ATOMIC macro, which is #error-incompatible with
CONFIG_PREEMPT_RT; the mutex state field (.irq_flags vs .preempt_reenabled)
follows the selected regime, and wc_lkm_UnlockMutex() moves out of line (with a
pie redirect table entry).
Add pre- and post-checks bracketing DRBG operations against the invalidation
recovery window (keyed off last_invalidation_at, stamped at invalidation). The
pre-check works as a waiting room, keeping callers from generating a CAS scan
storm during the invalidation recovery interval (during which there are no
usable RNGs system-wide). In the post-check, -EAGAIN passes through for another
lap, a window overrun returns -ETIMEDOUT, atomic-context callers get one-shot
-EBUSY (blockability is checked before signal state, because in hardirq context
`current` is an unrelated task), pending signals return -EINTR, and otherwise
the caller relaxes and retries. Both checks have stubs so reduced
configurations build, and in-window messaging is ratelimited.
Add emergency reinitialization of the entropy daemon's root_rng: when the
recovery sweep finds the root invalidated, the daemon retries
wc_RNG_DRBG_Reseed_Now() with an uncredited timestamp nonce while the failure
remains retryable (BUSY_E, NOT_READY_E, ENTROPY_RT_E, ENTROPY_APT_E), relaxing
between attempts; for the default bank the reseed runs with preemption disabled
to maximize its chances. If the reseed fails terminally, the daemon makes one
last-ditch recovery via wc_FreeRng() and wc_rng_bank_root_rng_init() (or
wc_InitRng() for a standalone root); a successful reinit always clears the
invalidated state. If that too fails, the daemon exits, leaving bank instances
to self-reseed. Outcomes are reported at severities differentiated by default
vs non-default bank (pr_notice/pr_info success, pr_emerg/pr_err failure). The
daemon also now supports a standalone malloc'd root_rng where no bank features
are built, instantiated at startup and freed on exit.
Also:
* wc_linuxkm_drbg_generate_tfm(): retry loop around the invalidation window
replaces the single-shot call; output buffer is zeroized on terminal error.
* wc__get_random_bytes(): honors the recovery window, and zeroizes its
staging buffer both before retry re-entry and on the error exit. An
invalidation may be peculiar to this VM and leave the bytes live in another
VM, so they are wiped when abandoned, as possible CSP elsewhere.
* wc_linuxkm_entropy_daemon(): the registered-leaf recovery pass is now
additionally gated on WC_LINUXKM_HAVE_RNG_REGISTRY, matching its actual
dependency; seed health test failures (ENTROPY_RT_E/ENTROPY_APT_E) on bank
instances are now reported unconditionally at pr_warn_ratelimited severity
("entropy source suspect"), rather than pr_err only under WC_VERBOSE_RNG;
the WC_RNG_DEBUG_STATS dump at daemon exit is removed (was redundant).
* wolfcrypt/test/test.c: SVR access-counter checks now additionally gated on
new WC_SVR_HAVE_FLAGS, matching the configurations that actually maintain
the counters.
wolfSSL linuxkm (linux kernel module)
libwolfssl supports building as a linux kernel module (libwolfssl.ko).
When loaded, wolfCrypt and wolfSSL API are made available to the rest of
the kernel, supporting cryptography and TLS in kernel space.
Performing cryptographic operations in kernel space has significant advantages over user space for high throughput network (VPN, IPsec, MACsec, TLS, etc) and filesystem (dm-crypt/LUKS, fscrypt disk encryption) IO processing, with the added benefit that keys can be kept isolated to kernel space. Additionally, when wolfCrypt-FIPS is used, this provides a simple recipe for FIPS-compliant kernels.
Supported features:
- crypto acceleration: AES-NI, AVX, etc.
- kernel crypto API registration (wolfCrypt algs appear as drivers in
/proc/crypto.). CONFIG_CRYPTO_FIPS, and crypto-manager self-tests.- FIPS-compliant patches to
drivers/char/random.c, covering kernels 5.10 to 6.15. - Supports FIPS-compliant WireGuard (https://github.com/wolfssl/wolfguard).
- TLS 1.3 and DTLS 1.3 kernel offload.
Building and Installing
Build libwolfssl.ko with:
$ ./configure --enable-linuxkm --with-linux-source=/usr/src/linux
$ make -j module
Note: Replace /usr/src/linux with a path to your fully configured and built
target kernel source tree.
If building from a FIPS kernel module bundle, build libwolfssl.ko with:
$ ./configure --enable-fips=fips_flavor --enable-linuxkm --with-linux-source=/usr/src/linux
$ make -j module-with-matching-fips-hash
Note: Replace fips_flavor with the correct value.
Assuming you are targeting your native system, install with:
$ sudo make install
$ sudo modprobe libwolfssl
Key additional Linux kernel module configuration options
| option | description |
|---|---|
--enable-linuxkm-lkcapi-register |
Register wolfcrypt algs with linux kernel crypto API. Optional value is 'all', 'all-kconfig', 'none', or a comma separated list of algs. |
--enable-all-crypto |
Enable extra crypto algorithms |
--enable-intelasm |
x86/amd64 crypto acceleration |
--enable-cryptonly |
Omit TLS/DTLS implementation (normally recommended) |
Enabling DTLS 1.3 in the kernel module
--enable-linuxkm does not implicitly enable TLS 1.3 or DTLS, so the DTLS 1.3
configure check (configure.ac:5634-5636) requires all three flags to be
passed explicitly:
./configure --enable-linuxkm \
--enable-tls13 --enable-dtls --enable-dtls13 \
--with-linux-source=/lib/modules/$(uname -r)/build
make -j$(nproc) module
The resulting linuxkm/libwolfssl.ko exports the DTLS 1.3 entry points
(wolfDTLSv1_3_client_method, wolfDTLSv1_3_server_method, etc.) as GPL
kernel symbols, available to other in-kernel consumers via
EXPORT_SYMBOL_GPL.
Additional configuration options for verification, performance evaluation, and troubleshooting
| option | description |
|---|---|
--enable-crypttests |
Run wolfcrypt_test() at module load (not recommended for production) |
--enable-kernel-benchmarks |
Run crypto benchmark at module load (not appropriate for production) |
--enable-kernel-verbose-debug |
Extra runtime diagnostic and informational messages |
--enable-kernel-stack-debug |
Report stack usage during module startup |
--enable-debug-trace-errcodes |
Profuse debug logging (not appropriate for production) |
--enable-debug-trace-errcodes=backtrace |
Even more profuse debug logging (not appropriate for production) |
Kernel Patches
The linuxkm/patches directory in the source distribution contains a patch to the linux kernel CRNG. The
CRNG provides the implementation for /dev/random, /dev/urandom, and
getrandom(), and for internal RNG APIs such as get_random_bytes(),
get_random_u32(), etc.
The patch applies to these two sources:
drivers/char/random.cinclude/linux/random.h
It adds a callback facility to the core kernel code that allows libwolfssl.ko
to register FIPS-compliant algorithms in place of the native implementation
(which is based on non-FIPS ChaCha20 and blake2s algorithms). When libwolfssl.ko is configured with
--enable-linuxkm-lkcapi-register and loaded into a patched kernel, it
automatically registers the FIPS callbacks. At startup, the module will report
libwolfssl: kernel global random_bytes handlers installed.
Additionally, /proc/crypto will advertise that the FIPS DRBG is installed at
highest priority, with "-wolfentropy" and/or "-rdseed", and "-with-global-replace":
name : stdrng
driver : sha2-256-drbg-nopr-wolfentropy-wolfcrypt-fips-140-3-with-global-replace
module : libwolfssl
priority : 100000
refcnt : 2
selftest : passed
internal : no
fips : yes
type : rng
seedsize : 0
Patches are provided for several kernel versions, ranging from 5.10.x to
6.15, with the most recent patchset tested nightly with the latest Linux
release and RC kernels, and with the latest linux-next snapshot. Use the
patchset with the most recent target kernel version not greater than that of the
kernel you're targeting.
Patch procedure
- Verify that the patcheset applies cleanly, using a dry run:
$ cd ~/kernelsrc/
$ patch -p1 --dry-run < ~/wolfssl-5.8.2/linuxkm/patches/6.12/WOLFSSL_LINUXKM_HAVE_GET_RANDOM_CALLBACKS-6v12.patch
checking file drivers/char/random.c
checking file include/linux/random.h
- Optionally, clean the kernel src tree before patching:
$ make mrproper
- Patch the kernel:
$ patch -p1 < ~/wolfssl-5.8.2/linuxkm/patches/6.12/WOLFSSL_LINUXKM_HAVE_GET_RANDOM_CALLBACKS-6v12.patch
patching file drivers/char/random.c
patching file include/linux/random.h
- Build and optionally install the patched kernel:
$ make -j
# make modules_install
# make install