Add nat20 integration test suite for linux examples by werwurm · Pull Request #105 · aurora-opensource/libnat20

werwurm · 2026-05-14T23:16:55Z

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.

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

…ple_nat20device

…le_libnat20

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

github-actions · 2026-05-14T23:19:12Z

LCOV of commit `a194dff` during lcov-test-coverage-report #233

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 Buildroot-packaged Linux/QEMU integration test suite for the nat20 service stack, including a new C test binary that exercises /dev/nat200, certificate issuance, signatures, parent paths, and promote behavior.

Changes:

Adds nat20_integration_test plus OpenSSL/libnat20-based verification helpers.
Adds QEMU/rootfs test launch scripts and Buildroot package wiring.
Extends CI to build the rootfs and run the integration test in QEMU.

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
`examples/linux/nat20test/test/test_helpers.h`	Declares helper APIs for test cryptographic verification and parsing.
`examples/linux/nat20test/test/test_helpers.c`	Implements OpenSSL, CBOR, COSE, and compression helpers.
`examples/linux/nat20test/test/nat20_integration_test.c`	Adds the main nat20 service integration test suite.
`examples/linux/nat20test/nat20test.sh`	Adds the test runner script for loading the module and launching the binary.
`examples/linux/nat20test/nat20_qemu_init.sh`	Adds the QEMU init wrapper for running tests and emitting result markers.
`examples/linux/nat20test/CMakeLists.txt`	Builds and installs the integration test binary and scripts.
`examples/linux/br_external/utils/envsetup.sh`	Adds nat20test override and rebuild support.
`examples/linux/br_external/package/nat20test/nat20test.mk`	Adds the Buildroot package definition for nat20test.
`examples/linux/br_external/package/nat20test/Config.in`	Adds the Buildroot config option for nat20test.
`examples/linux/br_external/package/nat20cli/nat20cli.mk`	Documents nat20cli override-source behavior.
`examples/linux/br_external/configs/qemu_br_defconfig`	Enables nat20test in the QEMU Buildroot config.
`examples/linux/br_external/Config.in`	Sources the new nat20test Buildroot config.
`.github/workflows/linux-kmod-build.yml`	Adds rootfs build and QEMU integration-test execution steps.

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

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.

…le_libnat20

…ple_integration_test

timhirsh · 2026-05-18T13:47:26Z

+      - name: Build rootfs image
+        env:
+          NAT20LIB_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20DEVICE_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20CRYPTO_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20SW_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          LIBNAT20_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20TEST_OVERRIDE_SRCDIR: ${{ github.workspace }}
+        run: make -C ${{ runner.temp }}/buildroot.build/buildroot -j $(( $(nproc) + 1 ))
+
+      - name: Run integration tests in QEMU
+        timeout-minutes: 5
+        run: |
+          BUILDROOT_DIR="${{ runner.temp }}/buildroot.build/buildroot"
+          KERNEL="${BUILDROOT_DIR}/output/images/bzImage"
+          ROOTFS="${BUILDROOT_DIR}/output/images/rootfs.ext2"
+
+          qemu-system-x86_64 \
+            -M pc \
+            -kernel "${KERNEL}" \
+            -drive file="${ROOTFS}",if=virtio,format=raw \
+            -append "rootwait root=/dev/vda console=ttyS0 init=/usr/bin/nat20test_qemu_init.sh" \
+            -nographic \
+            -no-reboot \
+            -net none \
+            2>&1 | tee qemu_output.log
+
+          if grep -q "INTEGRATION_TESTS_PASSED" qemu_output.log; then
+            echo "Integration tests passed."
+          else
+            echo "Integration tests failed. QEMU output:"
+            cat qemu_output.log
+            exit 1
+          fi


These changes are also present in #104. Based on the PR title, I think they should be here.. can you please separate them out so it's more clear?

You are correct, however, this PR is correct, so you should have approved this one and not #104.

Ultimately, both are correct in this respect, I just forgot to change the base on #104 which is supposed to land after this one. I corrected this now.

smacdude · 2026-05-18T22:03:49Z

+                                    uint8_t* compressed_out,
+                                    size_t compressed_out_size) {
+    n20_crypto_digest_context_t* digest_ctx = NULL;
+    n20_error_t err = n20_crypto_nat20_open(&digest_ctx);


Basically re-iterating what copilot said below. We don't close this in the success path or in any of the error paths.

smacdude · 2026-05-18T22:18:02Z

+    /* CDI1: subject_key_type × format, issuer = P-256, no parent path */
+    for (size_t si = 0; si < NUM_KEY_TYPES; si++) {
+        for (size_t fi = 0; fi < NUM_CDI_FORMATS; fi++) {
+            level1_artifacts.cdi1_valid[si][fi] = issue_cdi_cert(n20_crypto_key_type_secp256r1_e,


From the code below it looks like we are OK with some of these failing and other succeeding, but it's hard to derive the actual expectations just by looking at the code. It could be that the expectations will vary across devices/implementations, but this integration test is already pretty tightly coupled to the reference implementation.

Obviously Copilots suggestion of expecting them all to succeed is wrong, do it would be nice if we could at least validate that the expectations are met.

The same comment applies to cdi2_valid, eca_valid, eca_ee_valid, and signature valid.

why is copilots expectation of them all succeeding wrong? we should be able to successfully create all subject key types and formats.

I was just basing that on the following code that seemed OK (i.e. didn't fail) if valid is false.

smacdude · 2026-05-18T23:10:03Z

+            for (size_t fi = 0; fi < NUM_CDI_FORMATS; fi++) {
+                cert_buffer_t cert;
+                bool ok =
+                    issue_cdi_cert(KEY_TYPES[ii], KEY_TYPES[si], CDI_FORMATS[fi], no_path, &cert);


So each of these cases are expected to pass? Aren't these the same calls as were made in the level 1 test? Or does the promotion change their behavior from level1?

seidelrj · 2026-05-20T15:48:41Z

+        return err;
+    }
+
+    ssize_t received = dispatch_request(msg_buffer + (sizeof(msg_buffer) - msg_size),


does n20_msg_request_write work with a null buffer? then you can just run it twice so you can put the message at the start of the buffer.

seidelrj · 2026-05-20T15:52:13Z

+    TEST_PASS();
+}
+
+static void test_cdi_cert_x509_p256(void) {


should this test have a check with N20_WITH_X509 == 1 around it?

seidelrj · 2026-05-20T15:54:26Z

+}
+#endif
+
+static void test_eca_cert_x509_p256(void) {


same question as above and guarding with N20_WITH_X509 == 1

seidelrj · 2026-05-20T15:57:21Z

+        fprintf(stderr, "    cdi-cert error: 0x%x\n", cert_response.error_code);
+        return false;
+    }
+    if (cert_response.certificate.size > sizeof(out->data)) return false;


nit: brackets.

seidelrj · 2026-05-20T15:57:59Z

+        fprintf(stderr, "    eca-cert error: 0x%x\n", cert_response.error_code);
+        return false;
+    }
+    if (cert_response.certificate.size > sizeof(out->data)) return false;


nit: brackets.

seidelrj · 2026-05-20T15:58:56Z

+        fprintf(stderr, "    eca-ee-cert error: 0x%x\n", cert_response.error_code);
+        return false;
+    }
+    if (cert_response.certificate.size > sizeof(out->data)) return false;


nit: brackets.

seidelrj · 2026-05-20T15:59:28Z

+        fprintf(stderr, "    eca-ee-sign error: 0x%x\n", sign_response.error_code);
+        return false;
+    }
+    if (sign_response.signature.size > sizeof(out->data)) return false;


nit: brackets.

seidelrj · 2026-05-20T16:00:12Z

+
+static bool read_uds_cert(cert_buffer_t* out) {
+    int fd = open(DICE_CHAIN_PATH, O_RDONLY);
+    if (fd < 0) return false;


nit: brackets.

seidelrj · 2026-05-20T16:06:44Z

+    /* CDI1: subject_key_type × format, issuer = P-256, no parent path */
+    for (size_t si = 0; si < NUM_KEY_TYPES; si++) {
+        for (size_t fi = 0; fi < NUM_CDI_FORMATS; fi++) {
+            level1_artifacts.cdi1_valid[si][fi] = issue_cdi_cert(n20_crypto_key_type_secp256r1_e,


why is copilots expectation of them all succeeding wrong? we should be able to successfully create all subject key types and formats.

seidelrj · 2026-05-20T16:09:46Z

+                                                                 no_path,
+                                                                 &level1_artifacts.cdi1[si][fi]);
+        }
+    }


yeah i would fix this.

timhirsh

Approving GH actions changes.

werwurm added 30 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

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

Update license in package config.

1afed43

tidy

0eae0d8

Add SECURITY.md and fix some issues.

47f9055

fix error handling contract.

6a47870

address comments

54014fd

fixup KBuild

f645788

fixups

b621371

fix error path

b7b57a6

fix non standard deterministic DSA construction

502f49c

Change shash initialization order

f5e6efd

typo

3ded408

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

1957cd9

…ple_nat20device

Merge branch 'main' into werwurm/linux_example_nat20device

7fd4b5b

werwurm added 3 commits May 14, 2026 06:41

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.

Address comments

b7a2f03

werwurm force-pushed the werwurm/linux_example_integration_test branch from 783f03c to eaf904a Compare May 14, 2026 23:18

werwurm requested a review from Copilot May 14, 2026 23:19

Copilot started reviewing on behalf of werwurm May 14, 2026 23:19 View session

Copilot AI reviewed May 14, 2026

View reviewed changes

werwurm force-pushed the werwurm/linux_example_integration_test branch from eaf904a to 47500a2 Compare May 14, 2026 23:45

werwurm and others added 2 commits May 14, 2026 16:50

Apply suggestions from code review

8e3063f

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

address comments

bb95742

werwurm requested review from seidelrj and smacdude May 15, 2026 15:33

fix comma swallowing portability issue

2eac3fb

werwurm marked this pull request as ready for review May 15, 2026 15:44

werwurm requested a review from a team as a code owner May 15, 2026 15:44

Revert "Add nat20cli command line tool for nat20device."

b159fbb

This reverts commit 0612f25.

werwurm changed the base branch from werwurm/linux_example_nat20cli to werwurm/linux_example_libnat20 May 15, 2026 15:52

werwurm added 4 commits May 15, 2026 14:17

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

839b180

…le_libnat20

Merge branch 'main' into werwurm/linux_example_libnat20

3cfbb32

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

8739753

…ple_integration_test

Tidy test runner

89d1814

timhirsh reviewed May 18, 2026

View reviewed changes

Merge branch 'main' into werwurm/linux_example_integration_test

a194dff

werwurm changed the base branch from werwurm/linux_example_libnat20 to main May 18, 2026 15:09

werwurm requested a review from timhirsh May 18, 2026 15:10

smacdude requested changes May 18, 2026

View reviewed changes

seidelrj requested changes May 20, 2026

View reviewed changes

timhirsh approved these changes May 20, 2026

View reviewed changes

Conversation

werwurm commented May 14, 2026

Uh oh!

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

Uh oh!

LCOV of commit a194dff during lcov-test-coverage-report #233

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

timhirsh left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions Bot commented May 14, 2026 •

edited

Loading

LCOV of commit `a194dff` during lcov-test-coverage-report #233