Add nat20crypto module to linux examples (#100)

werwurm · web-flow · commit 128401a13b3b · 2026-05-12T08:52:10.000-07:00
The nat20crypto module implements the libnat20 crypto interface
in terms of linux kernel crypto primitives.
The module implements
- deterministic ECDSA with curves P256 and P384.
- Bytewise SHA-2 224/256/384/512
- HMAC
- HKDF

ED25519 is currently not supported.
diff --git a/.github/workflows/linux-kmod-build.yml b/.github/workflows/linux-kmod-build.yml
@@ -106,3 +106,18 @@ jobs:
           find ${{ runner.temp }}/buildroot.build -name 'nat20device.ko' | grep -q nat20device.ko
           echo "nat20device.ko built successfully:"
           find ${{ runner.temp }}/buildroot.build -name 'nat20device.ko' -exec ls -la {} \;
+
+      - name: Build nat20crypto kernel module
+        env:
+          NAT20LIB_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20CRYPTO_OVERRIDE_SRCDIR: ${{ github.workspace }}
+        run: |
+          cd ${{ runner.temp }}/buildroot.build/buildroot
+          make nat20crypto-dirclean
+          make nat20crypto -j $(( $(nproc) + 1 ))
+
+      - name: Verify nat20crypto.ko was produced
+        run: |
+          find ${{ runner.temp }}/buildroot.build -name 'nat20crypto.ko' | grep -q nat20crypto.ko
+          echo "nat20crypto.ko built successfully:"
+          find ${{ runner.temp }}/buildroot.build -name 'nat20crypto.ko' -exec ls -la {} \;
diff --git a/examples/linux/br_external/Config.in b/examples/linux/br_external/Config.in
@@ -33,5 +33,6 @@
 # along with this program; if not, see
 # <https://www.gnu.org/licenses/>.
 
+source "$BR2_EXTERNAL_NAT20_PATH/package/nat20crypto/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20device/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20lib/Config.in"
diff --git a/examples/linux/br_external/configs/qemu_br_defconfig b/examples/linux/br_external/configs/qemu_br_defconfig
@@ -3976,5 +3976,6 @@ BR2_TARGET_UBOOT_CUSTOM_PATCH_DIR=""
 #
 # Provides NAT20 related packages.
 #
+BR2_PACKAGE_NAT20CRYPTO=y
 BR2_PACKAGE_NAT20DEVICE=y
 BR2_PACKAGE_NAT20LIB=y
diff --git a/examples/linux/br_external/package/nat20crypto/Config.in b/examples/linux/br_external/package/nat20crypto/Config.in
@@ -0,0 +1,42 @@
+# Copyright 2026 Aurora Operations, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0
+#
+# This work is dual licensed.
+# You may use it under Apache-2.0 or GPL-2.0 at your option.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# OR
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+config BR2_PACKAGE_NAT20CRYPTO
+    bool "nat20crypto"
+    depends on BR2_PACKAGE_NAT20LIB
+    help
+        Add the nat20crypto kernel module. It implements
+        the libnat20 crypto interface in terms of linux
+        kernel crypto primitives.
diff --git a/examples/linux/br_external/package/nat20crypto/nat20crypto.mk b/examples/linux/br_external/package/nat20crypto/nat20crypto.mk
@@ -0,0 +1,48 @@
+# Copyright 2026 Aurora Operations, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0
+#
+# This work is dual licensed.
+# You may use it under Apache-2.0 or GPL-2.0 at your option.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# OR
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+NAT20CRYPTO_VERSION = origin/main
+NAT20CRYPTO_SITE = https://github.com/aurora-opensource/libnat20.git
+NAT20CRYPTO_SITE_METHOD = git
+NAT20CRYPTO_LICENSE = Apache-2.0 OR GPL-2.0
+NAT20CRYPTO_LICENSE_FILES = LICENSE-Apache-2.0.txt LICENSE-GPL-2.0.txt
+
+NAT20CRYPTO_DEPENDENCIES += nat20lib
+NAT20CRYPTO_MODULE_MAKE_OPTS += NAT20CRYPTO_NAT20LIB_DIR=$(NAT20LIB_DIR)/examples/linux/nat20lib
+
+NAT20CRYPTO_MODULE_SUBDIRS = examples/linux/nat20crypto
+
+$(eval $(kernel-module))
+$(eval $(generic-package))
diff --git a/examples/linux/br_external/utils/envsetup.sh b/examples/linux/br_external/utils/envsetup.sh
@@ -46,6 +46,7 @@ fi
 
 source .env
 
+export NAT20CRYPTO_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 export NAT20DEVICE_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 export NAT20LIB_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 
@@ -69,6 +70,7 @@ function brrebuild() {
         echo "Available targets:"
         echo "  all          - Rebuild all components"
         echo "  linux        - Rebuild the linux kernel"
+        echo "  nat20crypto  - Rebuild the nat20crypto module"
         echo "  nat20device  - Rebuild the nat20device module"
         echo "  nat20lib     - Rebuild the nat20lib library"
         popd
@@ -77,7 +79,7 @@ function brrebuild() {
 
     case "$1" in
         all)
-            ensure_popd make linux-rebuild nat20device-rebuild nat20lib-rebuild all
+            ensure_popd make linux-rebuild nat20crypto-rebuild nat20device-rebuild nat20lib-rebuild all
             ;;
         *)
             ensure_popd make $1-rebuild all
diff --git a/examples/linux/nat20crypto/Kbuild b/examples/linux/nat20crypto/Kbuild
@@ -0,0 +1,44 @@
+# Copyright 2026 Aurora Operations, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0
+#
+# This work is dual licensed.
+# You may use it under Apache-2.0 or GPL-2.0 at your option.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# OR
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+KBUILD_EXTRA_SYMBOLS := $(NAT20CRYPTO_NAT20LIB_DIR)/Module.symvers
+
+obj-m := nat20crypto.o
+
+# The following path is added to allow the module to include
+# crypto/ecc.h (or crypto/internal/ecc.h for 6.0+).
+ccflags-y := -I $(src)/include
+ccflags-y += -I $(srctree)
+ccflags-y += -I $(NAT20CRYPTO_NAT20LIB_DIR)/include
diff --git a/examples/linux/nat20crypto/Makefile b/examples/linux/nat20crypto/Makefile
@@ -0,0 +1,52 @@
+# Copyright 2026 Aurora Operations, Inc.
+#
+# SPDX-License-Identifier: Apache-2.0 OR GPL-2.0
+#
+# This work is dual licensed.
+# You may use it under Apache-2.0 or GPL-2.0 at your option.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+# OR
+#
+# This program is free software; you can redistribute it and/or
+# modify it under the terms of the GNU General Public License
+# as published by the Free Software Foundation; either version 2
+# of the License, or (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+KDIR ?= /lib/modules/`uname -r`/build
+INSTALL_MOD_PATH ?= /lib/modules/`uname -r`/extra
+
+NAT20CRYPTO_NAT20LIB_DIR ?= $(PWD)/../nat20lib
+
+all: modules
+
+modules:
+	$(MAKE) -C $(KDIR) M=$$PWD NAT20CRYPTO_NAT20LIB_DIR="$(NAT20CRYPTO_NAT20LIB_DIR)" modules
+
+modules_install:
+	$(MAKE) -C $(KDIR) M=$$PWD INSTALL_MOD_PATH="$(INSTALL_MOD_PATH)" modules_install
+
+clean:
+	$(MAKE) -C $(KDIR) M=$$PWD clean
+
+.PHONY: all modules modules_install clean
diff --git a/examples/linux/nat20crypto/SECURITY.md b/examples/linux/nat20crypto/SECURITY.md
@@ -0,0 +1,98 @@
+# Security Assessment - nat20crypto
+
+This module implements the libnat20 crypto interface in terms of
+kernel-provided primitives. It attempts to provide a functionally correct
+implementation and makes an effort to clean sensitive key material from
+memory. But it is **not suitable for production**, specifically the ECC
+signing operation is not constant-time and susceptible to leaking private
+key information through timing side channels.
+
+## Key Material Leak Analysis
+
+### Addressed
+
+- **`nat20crypto_sign`** — stack buffers `z`, `k`, `k_inv`, `rs` are wiped via
+  `memzero_explicit` on all exit paths. This covers the nonce, the inverted
+  nonce, the byte-swapped private key (in `k_inv` via the `key_bytes` alias),
+  and intermediate signature values.
+- **`nat20crypto_key_destroy`** — uses `memzero_explicit` before `kfree`.
+- **`nat20crypto_make_secret`** — the input `secret_in` buffer is caller-owned;
+  the output key is heap-allocated and properly zeroed on free.
+
+### Outstanding issues
+
+#### `n20_rfc6979_k_generation` internal state
+
+This function (from nat20lib) uses HMAC internally with the private key as
+input. Whether its internal buffers are zeroed depends on its implementation.
+Out of scope for this module but noted as a dependency.
+
+## Timing Side Channel Analysis
+
+### Threat model
+
+In a DICE boot-time context where signing happens once during module init with
+no concurrent attacker (single-threaded init, no network, no user interaction),
+timing side channels are not practically exploitable. For a general-purpose
+signing oracle accessible from userspace, the issues below would be exploitable.
+
+### High risk
+
+#### `vli_mod_inv` — variable-time modular inverse
+
+The kernel's `vli_mod_inv` computes the modular inverse of `k` using a binary
+extended GCD with data-dependent branches and loop counts. The number of
+iterations depends on the value of `k`, leaking nonce information through
+timing. Partial nonce knowledge enables private key recovery via lattice
+attacks.
+
+#### `ecc_make_pub_key` — variable-time point multiplication
+
+The kernel's ECC point multiplication uses a double-and-add algorithm. Older
+kernels (pre-6.10) use a naive implementation with data-dependent
+doublings/additions, leaking the scalar `k` through timing.
+
+### Medium risk
+
+#### `vli_mod_mult_slow` — conditional subtraction
+
+The kernel's `vli_mod_mult_slow` is a shift-and-add modular multiplication.
+The loop count is constant, but the conditional subtraction after each shift
+(`if (result >= mod) result -= mod`) is data-dependent. This leaks
+intermediate state of `d_A * r` and `k_inv * s`, exposing bits of the private
+key and nonce inverse.
+
+#### Conditional mod-n reduction branches
+
+```c
+if (vli_cmp(k, s, ndigits) <= 0) {
+    vli_sub(s, s, k, ndigits);
+} else {
+    /* addition path */
+}
+```
+
+The branch taken depends on `s` which embeds `d_A * r`, leaking information
+about the private key.
+
+### Low risk
+
+#### RFC 6979 / HMAC-SHA
+
+The kernel's SHA implementations are generally constant-time for the
+compression function. HMAC processes fixed-size blocks. Low timing risk.
+
+#### `ecc_swap_digits` / `memcpy` / simple copies
+
+These process a fixed number of bytes regardless of value. Constant-time.
+
+### Summary table
+
+| Operation | Timing risk | Impact |
+|---|---|---|
+| `vli_mod_inv(k_inv, k, ...)` | Variable-time | Nonce leak, key recovery |
+| `ecc_make_pub_key(k * G)` | Variable-time (pre-6.10) | Nonce leak, key recovery |
+| `vli_mod_mult_slow(s, d_A, r)` | Conditional subtract | Private key leak |
+| Conditional mod-n reduction | Branch on secret | Minor info leak |
+| RFC 6979 / HMAC-SHA | Constant-time | Safe |
+| `ecc_swap_digits` / copies | Constant-time | Safe |
diff --git a/examples/linux/nat20crypto/include/nat20crypto.h b/examples/linux/nat20crypto/include/nat20crypto.h
diff --git a/examples/linux/nat20crypto/nat20crypto.c b/examples/linux/nat20crypto/nat20crypto.c

Original file line number	Diff line number	Diff line change
`@@ -3976,5 +3976,6 @@ BR2_TARGET_UBOOT_CUSTOM_PATCH_DIR=""`
`3976`	`3976`	`#`
`3977`	`3977`	`# Provides NAT20 related packages.`
`3978`	`3978`	`#`
	`3979`	`+BR2_PACKAGE_NAT20CRYPTO=y`
`3979`	`3980`	`BR2_PACKAGE_NAT20DEVICE=y`
`3980`	`3981`	`BR2_PACKAGE_NAT20LIB=y`