Add linux example project. by werwurm · Pull Request #94 · aurora-opensource/libnat20

werwurm · 2026-04-07T21:46:01Z

No description provided.

github-actions · 2026-04-07T21:47:44Z

LCOV of commit `cee9a77` during lcov-test-coverage-report #231

Summary coverage rate:
  lines......: 95.6% (3048 of 3188 lines)
  functions..: 99.1% (232 of 234 functions)
  branches...: 87.1% (1658 of 1904 branches)

Files changed coverage rate: n/a

Copilot

Pull request overview

Adds a Linux-based example stack for libnat20, including kernel modules (device framework, crypto backend, software service) plus a userspace CLI and a Buildroot external tree to build/run the example (QEMU-focused).

Changes:

Introduces kernel modules: nat20device (char-dev framework), nat20crypto (Linux kernel crypto backend), nat20sw (software NAT20 service), and nat20lib (exports libnat20 symbols).
Adds nat20cli userspace tool + a shell script to exercise the kernel stack and verify cert chains.
Adds Buildroot br_external integration (packages, configs, bootstrap/env scripts, QEMU runner) and expands license-check coverage to include these file types.

Reviewed changes

Copilot reviewed 32 out of 34 changed files in this pull request and generated 14 comments.

Show a summary per file

File	Description
examples/linux/nat20sw/nat20sw.c	Software NAT20 service kernel module implementing dispatch + certificate read via `nat20device`.
examples/linux/nat20sw/Kbuild	Kbuild for building `nat20sw` against nat20 modules/symvers.
examples/linux/nat20lib/mod.c	Kernel module wrapper exporting selected libnat20 symbols for other modules.
examples/linux/nat20lib/Kbuild	Kbuild for compiling core libnat20 sources into a kernel module.
examples/linux/nat20device/nat20device.c	NAT20 device framework kernel module (char device + securityfs cert file).
examples/linux/nat20device/Kbuild	Kbuild for `nat20device`.
examples/linux/nat20device/include/nat20device.h	Public API for registering/unregistering NAT20 device drivers.
examples/linux/nat20crypto/nat20crypto.c	Linux-kernel-crypto-based implementation of nat20 crypto context.
examples/linux/nat20crypto/Kbuild	Kbuild for `nat20crypto` with include paths and symvers linkage.
examples/linux/nat20crypto/include/nat20crypto.h	Public header for opening/closing Linux crypto context + secret creation.
examples/linux/nat20cli/src/main.c	Userspace CLI to issue requests via `/dev/nat20X` and decode responses.
examples/linux/nat20cli/nat20clitest.sh	Script to load modules, run CLI flows, and verify produced cert chains.
examples/linux/nat20cli/CMakeLists.txt	CMake build for `nat20cli` against LibNat20 components.
examples/linux/br_external/utils/envsetup.sh	Helper functions/env exports for the Buildroot out-of-tree build dir.
examples/linux/br_external/run-qemu.sh	QEMU runner for the Buildroot-produced kernel + rootfs.
examples/linux/br_external/package/nat20sw/nat20sw.mk	Buildroot package definition for `nat20sw` kernel module.
examples/linux/br_external/package/nat20sw/Config.in	Buildroot menu entry for `nat20sw`.
examples/linux/br_external/package/nat20lib/nat20lib.mk	Buildroot package definition for `nat20lib` kernel module.
examples/linux/br_external/package/nat20lib/Config.in	Buildroot menu entry for `nat20lib`.
examples/linux/br_external/package/nat20device/nat20device.mk	Buildroot package definition for `nat20device` kernel module.
examples/linux/br_external/package/nat20device/Config.in	Buildroot menu entry + help text for `nat20device`.
examples/linux/br_external/package/nat20crypto/nat20crypto.mk	Buildroot package definition for `nat20crypto` kernel module.
examples/linux/br_external/package/nat20crypto/Config.in	Buildroot menu entry for `nat20crypto`.
examples/linux/br_external/package/nat20cli/nat20cli.mk	Buildroot package definition for installing `nat20cli`.
examples/linux/br_external/package/nat20cli/Config.in	Buildroot menu entry for `nat20cli`.
examples/linux/br_external/package/libnat20/libnat20.mk	Buildroot package definition for building/installing libnat20.
examples/linux/br_external/package/libnat20/Config.in	Buildroot menu entry for libnat20.
examples/linux/br_external/external.mk	Buildroot external-tree make include of all package `.mk`s.
examples/linux/br_external/external.desc	Buildroot external-tree metadata.
examples/linux/br_external/Config.in	Top-level Buildroot external-tree menu sources for NAT20 packages.
examples/linux/br_external/bootstrap.sh	Bootstrap script to create out-of-tree Buildroot build directory and seed configs.
.github/license-check/license-config.json	Extends license header checking to additional Buildroot/script file types.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-07T22:09:30Z

+void nat20device_unregister_driver(struct nat20device_driver* driver) {
+    struct nat20device_driver_instance* instance;
+
+    if (!driver) return;
+
+    instance = to_nat20device_instance(driver);
+
+    pr_info("NAT20: Unregistering driver instance %s%d\n", NAT20DEVICE_DEVICE_NAME, instance->id);
+


nat20device_unregister_driver() frees instance unconditionally, but open file descriptors keep a raw pointer to instance in file_priv->instance (set in nat20device_open). This can lead to use-after-free in subsequent read/write/release on those FDs after unregister. Consider reference counting the instance (e.g., kref) and only freeing after the last release, while making unregister mark the instance as inactive (e.g., set instance->ops = NULL) and remove device nodes/cdev.

Copilot · 2026-04-07T22:09:30Z

+    /* Dispatch the request */
+    ret = instance->ops->dispatch(instance->ctx, request_buf, count, &file_priv->response);
+    if (ret < 0) goto out;
+


nat20device_write() replaces the response buffer but never resets the file position. If the previous response was fully read, *f_pos will remain at the old end offset and the next read() will immediately return 0 (EOF). Reset *f_pos (and/or filp->f_pos) to 0 when a new response is produced.

Suggested change

/*

* A new response buffer is now available for this file; rewind the

* file position so the next read starts from the beginning.

*/

if (f_pos) *f_pos = 0;

filp->f_pos = 0;

Copilot · 2026-04-07T22:09:30Z

+ * The driver must allocate the response buffer, which will be freed by
+ * the framework using kfree after the read operation completes.


Header comment says the framework frees the response buffer "after the read operation completes", but the implementation only frees the buffer on the next write or on release() (it is not freed when read() reaches EOF). Please either update the documentation to match the actual lifetime or implement freeing when the response has been fully consumed.

Suggested change

* The driver must allocate the response buffer, which will be freed by

* the framework using kfree after the read operation completes.

* The driver must allocate the response buffer and must not free it after

* a successful return. The framework takes ownership of the buffer and

* frees it with kfree during later request/file cleanup (for example,

* before replacing it with a new response or when the device is released).

Copilot · 2026-04-07T22:09:31Z

+        kmalloc(sizeof(struct shash_desc) + crypto_shash_descsize(md_tfm), GFP_KERNEL);
+    if (md_ctx == NULL) {
+        crypto_free_shash(md_tfm);
+        printk(KERN_ERR "Failed to allocate hash descriptor: %ld\n", PTR_ERR(md_ctx));


On allocation failure md_ctx == NULL, the log uses PTR_ERR(md_ctx), but md_ctx is not an ERR_PTR (it's NULL). This prints a meaningless value and may confuse debugging. Log -ENOMEM or omit the error code here.

Suggested change

printk(KERN_ERR "Failed to allocate hash descriptor: %ld\n", PTR_ERR(md_ctx));

printk(KERN_ERR "Failed to allocate hash descriptor: %d\n", -ENOMEM);

Copilot · 2026-04-07T22:09:31Z

+    n20_rfc6979_k_generation(
+        &ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);


The return value from n20_rfc6979_k_generation() is ignored. If k-generation fails, subsequent operations (including modular inversion of k) may operate on an invalid/zero key and produce incorrect signatures or trigger errors. Capture and check the return value and fail early on error.

Suggested change

n20_rfc6979_k_generation(

&ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);

err = n20_rfc6979_k_generation(

&ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);

if (err) {

printk(KERN_ERR "Failed to generate signing nonce: %d\n", err);

return err;

}

Copilot · 2026-04-07T22:09:32Z

+            exit(EXIT_FAILURE);
+    }
+
+    // Stage 1: Determine command


argv[optind] is used without checking that optind < argc. Invoking nat20cli with no command (or after consuming options) will read past argv bounds and likely crash. Add an argc/optind check and print usage when no command is provided.

Suggested change

// Stage 1: Determine command

// Stage 1: Determine command

if (optind >= argc) {

print_usage(argv[0]);

exit(EXIT_FAILURE);

}

Copilot · 2026-04-07T22:09:32Z

+    size_t pos = 0;
+    if ((len & 1) != 0) {
+        // Odd length, assume leading zero
+        *out_pos++ = nibble2bits(hex[0]);


For odd-length hex strings, hex_string_to_bytes_in_place() writes nibble2bits(hex[0]) without validating it. If the first character is not valid hex, the function will write 0xFF (from -1) and continue instead of failing. Check nibble2bits(hex[0]) < 0 and return an error like the even-length path does.

Suggested change

*out_pos++ = nibble2bits(hex[0]);

int8_t low = nibble2bits(hex[0]);

if (low < 0) {

return -1; // Invalid hex character

}

*out_pos++ = low;

Copilot · 2026-04-07T22:09:33Z

+# along with this program; if not, see
+# <https://www.gnu.org/licenses/>.
+
+LIBNAT20_VERSION = origin/main


Using *_VERSION = origin/main for a Buildroot git package makes builds non-reproducible and can unexpectedly change when the branch moves. Prefer pinning to a specific tag or commit hash (and updating intentionally), especially since this external tree lives inside the same repository.

Suggested change

LIBNAT20_VERSION = origin/main

# Pin to an immutable revision for reproducible Buildroot builds.

LIBNAT20_VERSION = 0123456789abcdef0123456789abcdef01234567

Add a kernel module that provides libnat20 functionality to linux kernel modules. Also add a configuration to build a minimal linux image with buildroot and run in on qemu and a workflow to test build nat20lib.ko

…RIDE_DIR

This module creates a new character device class intended to implement the nat20 service protocol implementing DICE based device state attestation and an embedded CA.

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.

…/linux_example_nat20device

…urm/linux_example_nat20crypto

…nux_example_nat20sw

…le_libnat20

…linux_example_libnat20

…le_libnat20

This commandline tool provides a primitive interface to communicate with a nat20 device.

Adds a C integration test binary (nat20_integration_test) that exercises the full DICE service stack via /dev/nat200. The test generates certificate chains across all supported key type (P-256, P-384) and format (X.509, COSE) permutations, verifies cryptographic signatures at each link, and confirms that parent_path-based issuance produces identical results to direct issuance after promote. Test structure: - Phase 1 (level 1): Generate CDI1, CDI2, ECA, ECA_EE certs and signatures using parent paths of varying depth from the UDS level. Verify all X.509 and COSE chains cryptographically. - Phase 2 (level 2): After one promote, regenerate CDI2/ECA/ECA_EE/sign with reduced parent path depth and assert byte-for-byte equality. - Phase 3 (level 3): After second promote, regenerate ECA/ECA_EE/sign with no parent path and assert equality. Also includes: - test_helpers.c: OpenSSL-based X.509 signature verification, public key extraction, COSE_Sign1 parsing and verification, CWT subject public key extraction, and compressed input computation. - nat20_qemu_init.sh: init wrapper for running tests in QEMU CI. - GitHub Action steps to build the rootfs and run the test suite in QEMU. - Buildroot package (nat20test) with OpenSSL dependency.

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

This reverts commit 0612f25.

This reverts commit b159fbb.

…le_libnat20

…ple_integration_test

…nux_example_nat20cli

werwurm force-pushed the werwurm/example_linux branch from 88a216e to 2ac8879 Compare April 7, 2026 21:57

werwurm requested a review from Copilot April 7, 2026 22:01

Copilot started reviewing on behalf of werwurm April 7, 2026 22:01 View session

Copilot AI reviewed Apr 7, 2026

View reviewed changes

werwurm force-pushed the werwurm/example_linux branch 6 times, most recently from be3d097 to a978a54 Compare April 8, 2026 16:09

werwurm added 10 commits April 29, 2026 09:34

Add nat20lib kernel module example and br environment.

67ca3fc

Add a kernel module that provides libnat20 functionality to linux kernel modules. Also add a configuration to build a minimal linux image with buildroot and run in on qemu and a workflow to test build nat20lib.ko

Fixup lint and add Makefiles to license checker.

4070f76

Make bootstrap executable

de1ea2a

Use prebuild toolchain and stop building qemu from scratch.

36bc192

address comments and also resolve circular dependency when using OVER…

44c8f8f

…RIDE_DIR

Do not use relative paths

6627ce3

Add module nat20device to linux examples.

edbd436

This module creates a new character device class intended to implement the nat20 service protocol implementing DICE based device state attestation and an embedded CA.

Add nat20device to linux-kmod-build github action.

2fd948f

nat20device fixups

b9669af

werwurm force-pushed the werwurm/example_linux branch 2 times, most recently from b1d69fa to f0ee7c1 Compare May 4, 2026 23:39

werwurm added 7 commits May 4, 2026 17:10

Set override SRCDIR for dependencies.

49d4901

Address comments.

4b64988

Merge branch 'refs/heads/werwurm/linux_example_nat20lib' into werwurm…

b1899da

…/linux_example_nat20device

address comments

fee93e2

Serialize read and write access and document concurrency contracts.

e5a7001

Add macro for max instances

b491dbb

Merge branch 'refs/heads/werwurm/linux_example_nat20device' into werw…

6062a0b

…urm/linux_example_nat20crypto

werwurm added 12 commits May 12, 2026 09:01

Merge branch 'werwurm/fix_certificate_size_estimates' into werwurm/li…

d7d13bb

…nux_example_nat20sw

Merge branch 'main' into werwurm/linux_example_nat20sw

8808749

address comments

600e630

Merge branch 'werwurm/linux_example_nat20sw' into werwurm/linux_examp…

8b52e5f

…le_libnat20

address comments

1492110

Merge branch 'refs/heads/werwurm/linux_example_nat20sw' into werwurm/…

dfc343c

…linux_example_libnat20

Address comments

4be3210

Make nat20sw.mk consistent

f3f0549

Merge branch 'refs/heads/werwurm/linux_example_nat20sw' into werwurm/…

6bbee61

…linux_example_libnat20

address comments

7ffea18

Merge branch 'werwurm/linux_example_nat20sw' into werwurm/linux_examp…

42b2c9e

…le_libnat20

Add nat20cli command line tool for nat20device.

0612f25

This commandline tool provides a primitive interface to communicate with a nat20 device.

werwurm force-pushed the werwurm/example_linux branch from f0ee7c1 to d461087 Compare May 14, 2026 13:46

werwurm and others added 16 commits May 14, 2026 09:15

Address comments

b7a2f03

Apply suggestions from code review

8e3063f

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

address comments

bb95742

fix comma swallowing portability issue

2eac3fb

Revert "Add nat20cli command line tool for nat20device."

b159fbb

This reverts commit 0612f25.

Reapply "Add nat20cli command line tool for nat20device."

2a5a8b6

This reverts commit b159fbb.

Merge branch 'werwurm/linux_example_nat20sw' into werwurm/linux_examp…

839b180

…le_libnat20

Merge branch 'main' into werwurm/linux_example_libnat20

3cfbb32

polishing clitest

4e5acf5

Merge branch 'werwurm/linux_example_libnat20' into werwurm/linux_exam…

8739753

…ple_integration_test

Merge branch 'werwurm/linux_example_integration_test' into werwurm/li…

9ddc860

…nux_example_nat20cli

Tidy test runner

89d1814

Merge branch 'werwurm/linux_example_integration_test' into werwurm/li…

b34c143

…nux_example_nat20cli

Add documentation for linux example

967c20a

fixup module makefiles

cee9a77

werwurm force-pushed the werwurm/example_linux branch from d461087 to cee9a77 Compare May 16, 2026 16:02

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add linux example project.#94

Add linux example project.#94
werwurm wants to merge 71 commits into
mainfrom
werwurm/example_linux

werwurm commented Apr 7, 2026

Uh oh!

github-actions Bot commented Apr 7, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Copilot AI Apr 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

+    /*
+     * A new response buffer is now available for this file; rewind the
+     * file position so the next read starts from the beginning.
+     */
+    if (f_pos) *f_pos = 0;
+    filp->f_pos = 0;

		* The driver must allocate the response buffer, which will be freed by
		* the framework using kfree after the read operation completes.

- * The driver must allocate the response buffer, which will be freed by
- * the framework using kfree after the read operation completes.
+ * The driver must allocate the response buffer and must not free it after
+ * a successful return. The framework takes ownership of the buffer and
+ * frees it with kfree during later request/file cleanup (for example,
+ * before replacing it with a new response or when the device is released).

	printk(KERN_ERR "Failed to allocate hash descriptor: %ld\n", PTR_ERR(md_ctx));
	printk(KERN_ERR "Failed to allocate hash descriptor: %d\n", -ENOMEM);

		n20_rfc6979_k_generation(
		&ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);

-    n20_rfc6979_k_generation(
-        &ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);
+    err = n20_rfc6979_k_generation(
+        &ctx->digest_ctx, digest_algorithm, dicemod_key->type, &key_slice, &gather_list, &k_bn, 0);
+    if (err) {
+        printk(KERN_ERR "Failed to generate signing nonce: %d\n", err);
+        return err;
+    }

-        *out_pos++ = nibble2bits(hex[0]);
+        int8_t low = nibble2bits(hex[0]);
+        if (low < 0) {
+            return -1;  // Invalid hex character
+        }
+        *out_pos++ = low;

	LIBNAT20_VERSION = origin/main
	# Pin to an immutable revision for reproducible Buildroot builds.
	LIBNAT20_VERSION = 0123456789abcdef0123456789abcdef01234567

Conversation

werwurm commented Apr 7, 2026

Uh oh!

github-actions Bot commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

LCOV of commit cee9a77 during lcov-test-coverage-report #231

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions Bot commented Apr 7, 2026 •

edited

Loading

LCOV of commit `cee9a77` during lcov-test-coverage-report #231