Skip to content

fix: document FIPS v5 reseed suppression and genkey privilege requirement #18

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MarkAtwood wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix: document FIPS v5 reseed suppression and genkey privilege requirement #18

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -162,6 +162,14 @@ under `/lib/modules/` where the target kernel's modules are installed.
The `genkey` and `pubkey` ops in the final line are basic functionality tests.
If all is well, it will succeed, and print a random public key.

**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` (and
`wg-fips genkey`) offloads key generation to the kernel module via netlink and
therefore requires `CAP_NET_ADMIN`. Non-root users will receive a permission
error. To resolve this, either run as root or via `sudo`, or build `wg-fips`
with `NO_IPC_LLCRYPTO=1` (which selects the userspace key generation path), or
grant the `wg-fips` binary the `cap_net_admin` file capability
(`setcap cap_net_admin+ep wg-fips`).
Comment on lines +165 to +171
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This note states both wg genkey and wg-fips genkey are affected, but the remedies are wg-fips-specific (build wg-fips..., setcap ... wg-fips). To avoid confusing non-FIPS users, consider either (1) making the text consistently apply to both binaries (and show both setcap examples), or (2) clearly stating which binary names are present/expected in each install path. Also, setcap typically requires sudo; documenting that helps users avoid a second “permission denied” surprise.

Suggested change
**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` (and
`wg-fips genkey`) offloads key generation to the kernel module via netlink and
therefore requires `CAP_NET_ADMIN`. Non-root users will receive a permission
error. To resolve this, either run as root or via `sudo`, or build `wg-fips`
with `NO_IPC_LLCRYPTO=1` (which selects the userspace key generation path), or
grant the `wg-fips` binary the `cap_net_admin` file capability
(`setcap cap_net_admin+ep wg-fips`).
**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` and
`wg-fips genkey` offload key generation to the kernel module via netlink and
therefore require `CAP_NET_ADMIN`. Non-root users will receive a permission
error. To resolve this, either run as root or via `sudo`, build the binary
you are using with `NO_IPC_LLCRYPTO=1` (which selects the userspace key
generation path), or grant that binary the `cap_net_admin` file capability,
for example `sudo setcap cap_net_admin+ep wg-fips` or, if your install exposes
the tool as `wg`, `sudo setcap cap_net_admin+ep wg`.

Copilot uses AI. Check for mistakes.

As for the `wg-fips` build above, compressed public key support can be enabled
by adding `EXTRA_CFLAGS=-DWG_USE_PUBLIC_KEY_COMPRESSION` to the above `make`
recipe. The `WG_USE_PUBLIC_KEY_COMPRESSION` setting must be matched throughout
Expand Down Expand Up @@ -296,6 +304,14 @@ $ ../user-src/wg-fips genkey | ../user-src/wg-fips pubkey
The `genkey` and `pubkey` ops in the final line are basic functionality tests.
If all is well, it will succeed, and print a random public key.

**Note:** When the `wolfguard.ko` kernel module is loaded, `wg genkey` (and
`wg-fips genkey`) offloads key generation to the kernel module via netlink and
therefore requires `CAP_NET_ADMIN`. Non-root users will receive a permission
error. To resolve this, either run as root or via `sudo`, or build `wg-fips`
with `NO_IPC_LLCRYPTO=1` (which selects the userspace key generation path), or
grant the `wg-fips` binary the `cap_net_admin` file capability
(`setcap cap_net_admin+ep wg-fips`).

As with the non-FIPS-certified procedure, if all of the above succeeds, then you
are now ready to bring up WolfGuard tunnels. Existing playbooks and scripting
for WireGuard can be used directly, provided you substitute `/etc/wolfguard` for
Expand Down
7 changes: 7 additions & 0 deletions kernel-src/netlink.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -876,6 +876,13 @@ struct genl_ops genl_ops[] = {
#endif
.flags = GENL_UNS_ADMIN_PERM
}, {
/* Key generation is offloaded to the kernel module and
* therefore requires CAP_NET_ADMIN. Users without this
* privilege should either run via sudo/root, or build
* with NO_IPC_LLCRYPTO=1 to use the userspace key
* generation path, or ensure the wg-fips binary has the
* appropriate file capabilities set (e.g. cap_net_admin+ep).
Comment on lines +883 to +884
Copy link

Copilot AI Apr 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The comment is attached to a kernel netlink op (WG_CMD_GEN_PRIVKEY) and says “ensure the wg-fips binary has…” even though the same op may be invoked by wg as well (as described in the README note). Consider rewording to refer generically to the userspace client binary (e.g., “wg/wg-fips”) so the kernel-side comment stays accurate regardless of which frontend is used.

Suggested change
* generation path, or ensure the wg-fips binary has the
* appropriate file capabilities set (e.g. cap_net_admin+ep).
* generation path, or ensure the userspace client binary
* (e.g. wg/wg-fips) has the appropriate file capabilities
* set (e.g. cap_net_admin+ep).

Copilot uses AI. Check for mistakes.
*/
.cmd = WG_CMD_GEN_PRIVKEY,
.doit = wg_nl_generate_privkey,
.policy = device_policy,
Expand Down
4 changes: 4 additions & 0 deletions kernel-src/wolfcrypt_glue.c
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1196,6 +1196,10 @@ int wc_linuxkm_drbg_generate(struct wc_linuxkm_drbg_ctx *ctx,
retry:

#if defined(HAVE_FIPS) && FIPS_VERSION_LT(6,0)
/* FIPS v5 does not expose an API to externally reseed the DRBG.
* The entropy input is therefore discarded here. The DRBG output
* remains safe: it was properly seeded at initialization time.
*/
(void)src;
(void)slen;
#else
Expand Down