wolfssl-sys 4.0.0

System bindings for WolfSSL
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104

# 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.
- crypto acceleration: AES-NI, AVX, etc.

Planned features:
- kernel opencrypto driver registration (supported for internal testing presently).
- full wolfSSL in kernel (kernel TLS).

## Building and Installing

Build bsdkm with:

```sh
./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:

```sh
sudo kldload bsdkm/libwolfssl.ko
```

You should see it now:
```sh
kldstat -m libwolfssl
Id  Refs Name
509    1 libwolfssl
```

Unload with:
```sh
sudo kldunload libwolfssl
```

### options

| freebsdkm option                   | description                              |
| :--------------------------------- | :--------------------------------------- |
| --with-bsd-export-syms=LIST        | Export list of symbols as global. <br>. Options are 'all', 'none', or <br> comma separated list of symbols. |
| --with-kernel-source=PATH          | Path to kernel tree root (default `/usr/src/sys`) |
| --enable-kernel-benchmarks         | Run wolfcrypt benchmark at module load    |
| --enable-freebsdkm-crypto-register | Register with the FreeBSD kernel opencrypto <br>framework (preliminary, for testing) |

### 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):

```sh
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.
```sh
$ 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).
```sh
$ 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
```