Add linux example project.

.github/license-check/license-config.json

@@ -10,6 +10,7 @@
       "**/Kbuild",
       "examples/linux/br_external/external.desc",
       "examples/linux/**/Makefile",
+      "examples/linux/nat20cli/openssl_dice.cnf",
       ".clang-format",
       ".gitignore"
     ],

.github/workflows/linux-kmod-build.yml

@@ -49,7 +49,7 @@ jobs:
     steps:
       - uses: actions/checkout@44c2b7a8a4ea60a981eaca3cf939b5f4305c123b #v4.1.5
 
-      - name: Install Buildroot dependencies
+      - name: Install build and test dependencies
         run: |
           sudo apt-get update
           sudo apt-get install -y \
@@ -60,6 +60,7 @@ jobs:
             git \
             libncurses-dev \
             python3 \
+            qemu-system-x86 \
             rsync \
             unzip \
             wget
@@ -138,3 +139,93 @@ jobs:
           find ${{ runner.temp }}/buildroot.build -name 'nat20sw.ko' | grep -q nat20sw.ko
           echo "nat20sw.ko built successfully:"
           find ${{ runner.temp }}/buildroot.build -name 'nat20sw.ko' -exec ls -la {} \;
+
+      - name: Build libnat20 userspace library
+        env:
+          LIBNAT20_OVERRIDE_SRCDIR: ${{ github.workspace }}
+        run: |
+          cd ${{ runner.temp }}/buildroot.build/buildroot
+          make libnat20-dirclean
+          make libnat20 -j $(( $(nproc) + 1 ))
+
+      - name: Verify libnat20 was produced
+        run: |
+          find ${{ runner.temp }}/buildroot.build -name 'libnat20.a' | grep -q libnat20.a
+          echo "libnat20.a built successfully:"
+          find ${{ runner.temp }}/buildroot.build -name 'libnat20.a' -exec ls -la {} \;
+
+      - name: Build nat20cli userspace cli tool
+        env:
+          LIBNAT20_OVERRIDE_SRCDIR: ${{ github.workspace }}
+          NAT20CLI_OVERRIDE_SRCDIR: ${{ github.workspace }}
+        run: |
+          cd ${{ runner.temp }}/buildroot.build/buildroot
+          make nat20cli-dirclean
+          make nat20cli -j $(( $(nproc) + 1 ))
+
+      - name: Verify nat20cli was produced
+        run: |
+          find ${{ runner.temp }}/buildroot.build -name 'nat20cli' | grep -q nat20cli
+          echo "nat20cli built successfully:"
+          find ${{ runner.temp }}/buildroot.build -name 'nat20cli' -exec ls -la {} \;
+
+      - 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 }}
+          NAT20CLI_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
+
+      - name: Run nat20cli 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/nat20cli_qemu_init.sh" \
+            -nographic \
+            -no-reboot \
+            -net none \
+            2>&1 | tee qemu_output.log
+
+          if grep -q "NAT20CLI_TESTS_PASSED" qemu_output.log; then
+            echo "NAT20CLI tests passed."
+          else
+            echo "NAT20CLI tests failed. QEMU output:"
+            cat qemu_output.log
+            exit 1
+          fi

.gitignore

@@ -49,4 +49,3 @@ build/
 cmake_install.cmake
 compile_commands.json
 html/
-nat20test

README.md

@@ -96,6 +96,15 @@ make nat20_docs
 Open the documentation by pointing your browser to `html/index.html` in your
 build directory.
 
+## Examples
+
+### Linux DICE kernel modules
+
+The `examples/linux/` directory contains a complete Linux kernel module
+implementation of a software DICE node, including a userspace CLI tool and a
+Buildroot-based build environment targeting QEMU. See
+[examples/linux/README.md](examples/linux/README.md) for details.
+
 ## API Reference
 
 The API references is generated from the main branch using doxygen and deployed

examples/linux/README.md

@@ -0,0 +1,132 @@
+# Linux DICE Example
+
+This directory contains a set of Linux kernel modules and a userspace CLI tool
+that together implement a software DICE node using libnat20.
+
+## Architecture
+
+The example is structured as four kernel modules with the following dependency
+chain:
+
+```
+nat20sw  ──►  nat20crypto  ──►  nat20lib
+               nat20device  ──►
+```
+
+### nat20lib
+
+A kernel module wrapper around the core libnat20 C library. It compiles all
+core library sources (CBOR, COSE, CWT, X.509, HKDF, service dispatch) into a
+single `.ko` and re-exports their symbols via `EXPORT_SYMBOL()` so that other
+kernel modules can use them.
+
+### nat20crypto
+
+Implements the libnat20 crypto interface (`n20_crypto_context_t`) using the
+Linux kernel's crypto API. Provides ECDSA signing (P-256, P-384), HKDF key
+derivation, and SHA-2 hashing — all in kernel space.
+
+### nat20device
+
+A generic character device framework for DICE services. On load it allocates
+the `nat20` device class. Backend modules (like `nat20sw`) register via
+`nat20device_register_driver()`, which creates:
+
+- `/dev/nat20<N>` — a character device for DICE service requests (write a CBOR
+  request, read the CBOR response).
+- `/sys/kernel/security/nat20<N>/dice_chain` — a read-only securityfs file
+  exposing the boot-time DICE certificate chain.
+
+### nat20sw
+
+A concrete software DICE node that wires `nat20lib`, `nat20crypto`, and
+`nat20device` together. On load it derives a UDS from a hardcoded passphrase
+(for demonstration purposes only), issues a self-signed X.509 certificate, and
+registers itself with the `nat20device` framework.
+
+### nat20cli
+
+A userspace command-line tool that communicates with the DICE service via
+`/dev/nat200`. It can issue CDI certificates, ECA certificates, and advance
+the DICE layer via the `promote` command.
+
+## The `dice_chain` securityfs interface
+
+Each registered nat20device driver instance exposes a `dice_chain` file at
+`/sys/kernel/security/nat20<N>/dice_chain`. This file contains the DICE
+certificate chain constructed during bootup, encoded as a CBOR
+indefinite-length array.
+
+### Encoding
+
+The file contains a single CBOR indefinite-length array (`0x9f ... 0xff`).
+Each element in the array is one of the following CBOR-tagged values:
+
+| CBOR tag | Content | Description |
+|----------|---------|-------------|
+| `#6.80150(bstr)` | DER-encoded X.509 certificate | An X.509 certificate, typically with the Open DICE Input extension (OID `1.3.6.1.4.1.11129.2.1.24`). |
+| `#6.18(COSE_Sign1)` | COSE_Sign1 with CWT payload | A COSE certificate as specified by the Open DICE profile or a similar custom DICE profile. |
+| `#8.80152(COSE_Key)` | COSE_Key | A public key. |
+
+### Ordering and semantics
+
+- The first element represents the root device identity key. It may be a
+  self-signed certificate, a CA-signed certificate, or a bare public key
+  (`#8.80152`).
+- A benign implementation orders the remaining certificates from root to leaf.
+- The chain only contains certificates generated during bootup. Userspace is
+  responsible for managing additional CDI certificates issued via the
+  `/dev/nat20<N>` character device.
+
+## Building with Buildroot
+
+The `br_external/` directory provides a Buildroot external tree for building
+all components targeting a QEMU x86_64 virtual machine.
+
+```sh
+# Bootstrap the Buildroot environment (build directory must be outside the repo)
+BUILDROOT_DIR=/path/to/buildroot.build
+examples/linux/br_external/bootstrap.sh qemu $BUILDROOT_DIR
+
+# Build everything
+cd $BUILDROOT_DIR/buildroot
+make
+```
+
+### Local development
+The bootstrap script installs a file `envsetup.sh` in `$BUILDROOT_DIR`
+which sets the `*_OVERRIDE_SRCDIR`s for all of the packages nat20* etc.,
+and defines helper functions for rebuilding and running the result in
+qemu.
+
+```
+# Source the environment
+cd $BUILDROOT_DIR
+. envsetup.sh
+
+# Rebuild a package and the rootfs, this is equivalent to
+# pushd $BUILDROOT_DIR/buildroot
+# make nat20sw-rebuild all
+# popd
+brrebuild nat20sw
+
+# Rebuild all packages and the rootfs
+brrebuild all
+
+# Run the resulting rootfs and kernel in qemu
+run-qemu
+
+# Run the nat20cli test in qemu and shut down the emulator
+run-nat20cli-test
+
+# Run the nat20test integration test in qemu and sht down the emulator
+run-nat20test-test
+```
+
+### Caveat - `bootstrap.sh`
+The bootstrap script is usefull for setting up the development environment
+once, but it cannot keep the build root environment in sync with the upstream
+repository. When pulling the upstream repository and changes where made to
+`envsetup.sh`, `bootstrap.sh`, or the buildroot config, it may be necessary
+to bootstrap a new environment. A savvy user may track the changes and manually
+update the environment to save 30 minutes rebuilding the build root environment.

examples/linux/br_external/Config.in

@@ -33,7 +33,10 @@
 # along with this program; if not, see
 # <https://www.gnu.org/licenses/>.
 
+source "$BR2_EXTERNAL_NAT20_PATH/package/nat20cli/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20crypto/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20device/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20sw/Config.in"
 source "$BR2_EXTERNAL_NAT20_PATH/package/nat20lib/Config.in"
+source "$BR2_EXTERNAL_NAT20_PATH/package/libnat20/Config.in"
+source "$BR2_EXTERNAL_NAT20_PATH/package/nat20test/Config.in"

examples/linux/br_external/bootstrap.sh

@@ -99,6 +99,7 @@ pushd ${LIBNAT20_BR_BUILD_DIR}
 
 echo "LIBNAT20_BR_BUILD_DIR=${LIBNAT20_BR_BUILD_DIR}" | tee .env
 echo "LIBNAT20_ROOT=${LIBNAT20_ROOT}" | tee -a .env
+echo "LIBNAT20_PROJECT=${PROJECT}" | tee -a .env
 
 cp ${LIBNAT20_ROOT}/examples/linux/br_external/utils/envsetup.sh ./
 
@@ -109,7 +110,6 @@ git clone --depth 1 --branch "2025.08.1" https://gitlab.com/buildroot.org/buildr
 case "$PROJECT" in
 	qemu)
 		cp ${LIBNAT20_ROOT}/examples/linux/br_external/configs/qemu_br_defconfig buildroot/.config
-		cp ${LIBNAT20_ROOT}/examples/linux/br_external/run-qemu.sh ./
 		;;
 	esac
 

examples/linux/br_external/configs/qemu_br_defconfig

@@ -3976,7 +3976,10 @@ BR2_TARGET_UBOOT_CUSTOM_PATCH_DIR=""
 #
 # Provides NAT20 related packages.
 #
+BR2_PACKAGE_NAT20CLI=y
 BR2_PACKAGE_NAT20CRYPTO=y
 BR2_PACKAGE_NAT20DEVICE=y
 BR2_PACKAGE_NAT20SW=y
 BR2_PACKAGE_NAT20LIB=y
+BR2_PACKAGE_LIBNAT20=y
+BR2_PACKAGE_NAT20TEST=y

examples/linux/br_external/package/libnat20/Config.in

@@ -0,0 +1,39 @@
+# 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_LIBNAT20
+    bool "libnat20"
+    help
+        Add the libnat20 DICE library