wolfssl/bsdkm/README.md

wolfSSL bsdkm (bsd kernel module)

libwolfssl supports building as a FreeBSD kernel module (libwolfssl.ko). When loaded, wolfCrypt is made available to the rest of the kernel, allowing other loadable modules to link to wolfCrypt.

Supported features:

• wolfCrypt in kernel.
• FIPS-wolfcrypt.

Planned features:

• crypto acceleration: AES-NI, AVX, etc.
• kernel opencrypto driver registration.
• full wolfSSL in kernel (kernel TLS).

Building and Installing

Build bsdkm with:

./configure --enable-freebsdkm --enable-cryptonly && make

The default freebsdkm build assumes kernel source tree root at /usr/src/sys/. Use --with-kernel-source=PATH to configure a different path.

Assuming you are targeting your native system, install with:

sudo kldload bsdkm/libwolfssl.ko

You should see it now:

kldstat -m libwolfssl
Id  Refs Name
509    1 libwolfssl

Unload with:

sudo kldunload libwolfssl

options

freebsdkm option	description
--with-bsd-export-syms=LIST	Export list of symbols as global. . Options are 'all', 'none', or comma separated list of symbols.
--with-kernel-source=PATH	Path to kernel tree root (default /usr/src/sys)

FIPS

Building with FIPS is largely the same, with the additional step of configuring a fips hash.

1. Build bsdkm (the fips_hash here is a placeholder):

fips_hash=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef
./configure --enable-freebsdkm --enable-cryptonly --enable-fips=v6 \
  CFLAGS="-DWOLFCRYPT_FIPS_CORE_HASH_VALUE=$fips_hash" && make

2. Attempt first install. This is expected to fail, because the hash was a placeholder.

$ sudo kldload bsdkm/libwolfssl.ko
kldload: an error occurred while loading module bsdkm/libwolfssl.ko. Please check dmesg(8) for more details.

3. Check dmesg output for the updated hash value (yours will be different).

$ dmesg | tail -n5
In-core integrity hash check failure.
Rebuild with "WOLFCRYPT_FIPS_CORE_HASH_VALUE=3B144A08F291DBA536324646BBD127447B8F222D29A135780E330351E0DF9F0F".
error: wc_RunAllCast_fips failed at shutdown with return value 19
info: libwolfssl unloaded
module_register_init: MOD_LOAD (libwolfssl_fips, 0xffffffff842c28d0, 0) error 85

4. Repeat steps 1-2 with the new hash value. The load should succeed now.

$ kldstat -m libwolfssl_fips
Id  Refs Name
523    1 libwolfssl_fips

Unload with

sudo kldunload libwolfssl

On unload, the FIPS self-test will run a final time and print its status to system message buffer:

info: wolfCrypt FIPS re-self-test succeeded at unload: all algorithms re-verified.
info: libwolfssl unloaded