Add nat20cli command line tool for nat20device.

werwurm · werwurm · commit 0612f25187bc · 2026-05-14T06:43:38.000-07:00
This commandline tool provides a primitive interface to communicate with
a nat20 device.
diff --git a/.github/license-check/license-config.json b/.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"
     ],
diff --git a/.github/workflows/linux-kmod-build.yml b/.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
@@ -152,3 +153,18 @@ jobs:
           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 {} \;
diff --git a/examples/linux/br_external/Config.in b/examples/linux/br_external/Config.in
@@ -33,6 +33,7 @@
 # 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"
diff --git a/examples/linux/br_external/configs/qemu_br_defconfig b/examples/linux/br_external/configs/qemu_br_defconfig
@@ -3976,6 +3976,7 @@ 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
diff --git a/examples/linux/br_external/package/nat20cli/Config.in b/examples/linux/br_external/package/nat20cli/Config.in
@@ -0,0 +1,40 @@
+# 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_NAT20CLI
+    bool "nat20cli"
+    depends on BR2_PACKAGE_LIBNAT20
+    help
+        Enable building the nat20cli tool.
diff --git a/examples/linux/br_external/package/nat20cli/nat20cli.mk b/examples/linux/br_external/package/nat20cli/nat20cli.mk
@@ -0,0 +1,47 @@
+# 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/>.
+
+NAT20CLI_VERSION = origin/main
+NAT20CLI_SITE = https://github.com/aurora-opensource/libnat20.git
+NAT20CLI_SITE_METHOD = git
+NAT20CLI_LICENSE = Apache-2.0 OR GPL-2.0
+NAT20CLI_LICENSE_FILES = LICENSE-Apache-2.0.txt LICENSE-GPL-2.0.txt
+
+NAT20CLI_SUBDIR = examples/linux/nat20cli
+
+NAT20CLI_INSTALL_TARGET = YES
+NAT20CLI_DEPENDENCIES += libnat20
+
+$(eval $(cmake-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 NAT20CLI_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 export NAT20CRYPTO_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 export NAT20SW_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
 export NAT20DEVICE_OVERRIDE_SRCDIR="$LIBNAT20_ROOT"
@@ -72,6 +73,7 @@ function brrebuild() {
         echo "Available targets:"
         echo "  all          - Rebuild all components"
         echo "  linux        - Rebuild the linux kernel"
+        echo "  nat20cli     - Rebuild the Dice CLI"
         echo "  nat20crypto  - Rebuild the nat20crypto module"
         echo "  libnat20     - Rebuild the libnat20 library"
         echo "  nat20device  - Rebuild the nat20device module"
@@ -83,7 +85,7 @@ function brrebuild() {
 
     case "$1" in
         all)
-            ensure_popd make linux-rebuild nat20lib-rebuild nat20crypto-rebuild nat20device-rebuild nat20sw-rebuild libnat20-rebuild all
+            ensure_popd make linux-rebuild nat20lib-rebuild nat20crypto-rebuild nat20device-rebuild nat20sw-rebuild libnat20-rebuild nat20cli-rebuild all
             ;;
         *)
             ensure_popd make $1-rebuild all
diff --git a/examples/linux/nat20cli/CMakeLists.txt b/examples/linux/nat20cli/CMakeLists.txt
@@ -0,0 +1,82 @@
+# 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/>.
+
+cmake_minimum_required(VERSION 3.22)
+
+project(NAT20CLI VERSION 0.0.1 LANGUAGES C)
+
+# The C standard shall be C11.
+set(CMAKE_C_STANDARD 11)
+
+# CMake shall generate a compile_commands.json file for
+# the benfit of clangd based IDE support.
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
+
+###################################################################################################
+# The following section defines all the groups of source files.
+# All files must be specified explicitly; no globbing or other generation is allowed.
+
+set(NAT20CLI_SOURCES
+    # Add the core library source files here.
+    src/main.c
+)
+
+###################################################################################################
+
+###################################################################################################
+# The nat20_service library is also part of the product of this project.
+# It will always be compiled.
+add_executable(nat20cli)
+
+find_package(LibNat20 REQUIRED)
+
+target_sources(nat20cli
+	PRIVATE ${NAT20CLI_SOURCES}
+)
+
+target_link_libraries(nat20cli PRIVATE LibNat20::nat20 LibNat20::nat20_service LibNat20::nat20_crypto_nat20)
+
+target_compile_options(nat20cli
+    PRIVATE -pedantic
+    PRIVATE -Wall
+    PRIVATE -Wextra
+    PRIVATE -Werror
+)
+
+install(TARGETS nat20cli RUNTIME DESTINATION bin)
+install(PROGRAMS nat20clitest.sh DESTINATION bin)
+install(FILES openssl_dice.cnf DESTINATION bin)
+
+###################################################################################################
diff --git a/examples/linux/nat20cli/nat20clitest.sh b/examples/linux/nat20cli/nat20clitest.sh
@@ -0,0 +1,82 @@
+#!/bin/sh
+
+# 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/>.
+
+set -e
+
+SCRIPT_DIR="$(dirname "$0")"
+export OPENSSL_CONF="${SCRIPT_DIR}/openssl_dice.cnf"
+
+modprobe nat20sw
+mount -t securityfs none /sys/kernel/security
+
+nat20cli cdi-cert --key-type p256 --parent-key-type p256 --output cdi_0.der --certificate-format x509 --code-desc 795375622d322e332e343a33386334353963666164666132623839353333363939353465313266373534386433613161633937336338383830303563336236646232333436636263386631 --code 228d8f76c811276e991012cf5f46090377fc72c95a6ef9e1ccd4eebec8997be5b57f0fb2c7f4804af212711e7b49533f8bc00ddee9480f76155b3da1101604b9 --conf-desc 45787472616f7264696e617279206e6f726d616c20636f6e66696775726174696f6e --conf 671e957aff5565a55961dcaef7634f1a665d8f286e7bd99593532741417f22981b57bdc39241c9685f7377e3622067c261c3ce974e6db5f18d121adad2d76185 --auth-desc 41206365727469666963617465 --auth 50808e4ab921ecf31ca5f662b6d8b85b98ec4d3f64175c8b5d70c1f0e2fef048f87b3178907e1f2d652bd8588fa84f4c374347cc34b97dae13a5b981790b38cb --mode normal --hidden 2f299d2cc916e5219a6bcbc14c7135fa25e9a71018c2bafe8c0658d4041de6c87aa444aedcc68e7d7674b81b5838be1b74bf19d4d6fb05fb0db9ee7e297afc09
+nat20cli cdi-cert --key-type p256 --parent-key-type p256 --output cdi_0.cose --certificate-format cose --code-desc 795375622d322e332e343a33386334353963666164666132623839353333363939353465313266373534386433613161633937336338383830303563336236646232333436636263386631 --code 228d8f76c811276e991012cf5f46090377fc72c95a6ef9e1ccd4eebec8997be5b57f0fb2c7f4804af212711e7b49533f8bc00ddee9480f76155b3da1101604b9 --conf-desc 45787472616f7264696e617279206e6f726d616c20636f6e66696775726174696f6e --conf 671e957aff5565a55961dcaef7634f1a665d8f286e7bd99593532741417f22981b57bdc39241c9685f7377e3622067c261c3ce974e6db5f18d121adad2d76185 --auth-desc 41206365727469666963617465 --auth 50808e4ab921ecf31ca5f662b6d8b85b98ec4d3f64175c8b5d70c1f0e2fef048f87b3178907e1f2d652bd8588fa84f4c374347cc34b97dae13a5b981790b38cb --mode normal --hidden 2f299d2cc916e5219a6bcbc14c7135fa25e9a71018c2bafe8c0658d4041de6c87aa444aedcc68e7d7674b81b5838be1b74bf19d4d6fb05fb0db9ee7e297afc09
+nat20cli promote -i 790fd72ee1352017d822773bc8f5c1ac6e4bf310dfac72fbff622368c01372bc78324f0c06cbc37964e32b18588560a386357e4517ffe93052c67fe6213c38bc
+nat20cli cdi-cert --key-type p256 --parent-key-type p256 --output cdi_1.der --certificate-format x509 --code-desc 795375622d322e332e343a33386334353963666164666132623839353333363939353465313266373534386433613161633937336338383830303563336236646232333436636263386631 --code 228d8f76c811276e991012cf5f46090377fc72c95a6ef9e1ccd4eebec8997be5b57f0fb2c7f4804af212711e7b49533f8bc00ddee9480f76155b3da1101604b9 --conf-desc 45787472616f7264696e617279206e6f726d616c20636f6e66696775726174696f6e --conf 671e957aff5565a55961dcaef7634f1a665d8f286e7bd99593532741417f22981b57bdc39241c9685f7377e3622067c261c3ce974e6db5f18d121adad2d76185 --auth-desc 41206365727469666963617465 --auth 50808e4ab921ecf31ca5f662b6d8b85b98ec4d3f64175c8b5d70c1f0e2fef048f87b3178907e1f2d652bd8588fa84f4c374347cc34b97dae13a5b981790b38cb --mode normal --hidden 2f299d2cc916e5219a6bcbc14c7135fa25e9a71018c2bafe8c0658d4041de6c87aa444aedcc68e7d7674b81b5838be1b74bf19d4d6fb05fb0db9ee7e297afc09
+nat20cli cdi-cert --key-type p256 --parent-key-type p256 --output cdi_1.cose --certificate-format cose --code-desc 795375622d322e332e343a33386334353963666164666132623839353333363939353465313266373534386433613161633937336338383830303563336236646232333436636263386631 --code 228d8f76c811276e991012cf5f46090377fc72c95a6ef9e1ccd4eebec8997be5b57f0fb2c7f4804af212711e7b49533f8bc00ddee9480f76155b3da1101604b9 --conf-desc 45787472616f7264696e617279206e6f726d616c20636f6e66696775726174696f6e --conf 671e957aff5565a55961dcaef7634f1a665d8f286e7bd99593532741417f22981b57bdc39241c9685f7377e3622067c261c3ce974e6db5f18d121adad2d76185 --auth-desc 41206365727469666963617465 --auth 50808e4ab921ecf31ca5f662b6d8b85b98ec4d3f64175c8b5d70c1f0e2fef048f87b3178907e1f2d652bd8588fa84f4c374347cc34b97dae13a5b981790b38cb --mode normal --hidden 2f299d2cc916e5219a6bcbc14c7135fa25e9a71018c2bafe8c0658d4041de6c87aa444aedcc68e7d7674b81b5838be1b74bf19d4d6fb05fb0db9ee7e297afc09
+
+openssl x509 -inform der -outform pem -in cdi_0.der -out cdi_0.pem
+openssl x509 -inform der -outform pem -in cdi_1.der -out cdi_1.pem
+
+# The dice chain is formatted as variable length CBOR array
+# with each element being a tagged certificate.
+# Here, it is assumed the the chain contains only the semi hardcoded UDS certificate
+# from the nat20sw example, which is the only certificate in the chain.
+# arr (#6.80150 (bytes(DER encoded cert)))
+# tail -c+10 strips off the first 9 bytes:
+# The variable lenght array header (1 byte 0x9f)
+# The certificate tag (5 bytes)
+# The bytes header (3 bytes)
+# The head -c-1 strips off the last byte, which is the CBOR "break" byte (0xff) for the variable length array.
+# The resulting uds_cert.der file is the DER encoded UDS certificate, which can be parsed with standard tools.
+tail -c+10 /sys/kernel/security/nat200/dice_chain | head -c-1 > uds_cert.der
+
+openssl x509 -inform der -in uds_cert.der -outform pem -out uds_cert_p256.pem
+
+cat uds_cert_p256.pem cdi_0.pem > chain.pem
+
+openssl x509 -inform pem -in uds_cert_p256.pem -noout -text
+openssl x509 -inform pem -in cdi_0.pem -noout -text
+openssl x509 -inform pem -in cdi_1.pem -noout -text
+
+# Verify the certificate chain. The UDS certificate is self-signed, so it is the trust anchor for the chain.
+# The -ignore_critical flag is needed to ignore the critical extension in the UDS certificate,
+# which is not understood by OpenSSL but is required by the DICE specification. This check
+# only verifies the signatures and the certificate format, not the critical extension semantics.
+openssl verify -ignore_critical -CAfile chain.pem cdi_1.pem
+
+echo "OpenSSL chain verification passed."
diff --git a/examples/linux/nat20cli/openssl_dice.cnf b/examples/linux/nat20cli/openssl_dice.cnf
diff --git a/examples/linux/nat20cli/src/main.c b/examples/linux/nat20cli/src/main.c

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