Nzyme Util

The nzyme-util command is made to help you with common Nzyme tasks and especially to manage Nzyme hardware and peripherals.

Installation

Download the latest version of nzyme-util for your operating system and install it like this:

sudo dpkg -i nzyme-util_xxx-xxx-xxx-x.x.x.deb

You can now execute nzyme-util. Run the --help command to make sure it works:

$ nzyme-util --help

Nzyme CLI Utility

Usage: nzyme-util [COMMAND]

Commands:
  firmware
  devices
  help      Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

`udev` Rules

You can install the following udev rule to avoid having to be root to interact with Nzyme devices. It allows non-root users to use all USB devices with the Nzyme vendor ID 0x390C.

Write the following file to /etc/udev/rules.d/99-nzyme-usb.rules:

SUBSYSTEM=="usb", ATTR{idVendor}=="390c", MODE="0666"

Then reload the udev rules:

sudo udevadm control --reload-rules
sudo udevadm trigger

Confirm that the rule took effect:

$ udevadm cat | grep 390c
SUBSYSTEM=="usb", ATTR{idVendor}=="390c", MODE="0666"

You can decide not to install this udev rule, but you will have to be root or use sudo to run nzyme-util when interacting with Nzyme devices via USB.

Commands

List All Connected Nzyme Devices

You can list all connected Nzyme devices like this:

nzyme-util devices list

This will show you relevant information for each connected Nzyme device:

Device:
├─ Product:          Limina
├─ Manufacturer:     Nzyme LLC
├─ Serial:           207C309A3645
├─ Firmware Version: v0.0
├─ VID:PID:          390C:0200
├─ Bus / Address:    1 / 5
└─ ACM Port:         /dev/ttyACM0

Device:
├─ Product:          Sona (802.11/WiFi)
├─ Manufacturer:     Nzyme LLC
├─ Serial:           7C9085C8E6BDAAD1
├─ Firmware Version: v0.5
├─ VID:PID:          390C:0100
├─ Bus / Address:    1 / 51
└─ ACM Port:         /dev/ttyACM2

Device:
├─ Product:          Sona (802.11/WiFi)
├─ Manufacturer:     Nzyme LLC
├─ Serial:           8B7B63E05F374C94
├─ Firmware Version: v0.5
├─ VID:PID:          390C:0100
├─ Bus / Address:    1 / 50
└─ ACM Port:         /dev/ttyACM1

Device:
├─ Product:          Sona (802.11/WiFi)
├─ Manufacturer:     Nzyme LLC
├─ Serial:           B47277283036FD2F
├─ Firmware Version: v0.5
├─ VID:PID:          390C:0100
├─ Bus / Address:    1 / 55
└─ ACM Port:         /dev/ttyACM4

Device:
├─ Product:          Sona (802.11/WiFi)
├─ Manufacturer:     Nzyme LLC
├─ Serial:           1ABAE79791F91419
├─ Firmware Version: v0.5
├─ VID:PID:          390C:0100
├─ Bus / Address:    1 / 52
└─ ACM Port:         /dev/ttyACM3

Generate Sona Configuration

You can automatically generate an optimized Sona configuration snippet for your nzyme-tap configuration file.

nzyme-util sona generate-config

This will generate a configuration snippet that makes use of all connected Sona boards, splitting channels evenly.

==> Sona Configuration Generator
    Generating configuration for all connected Sona devices.

[>] Detecting connected Sona devices...
[*] Found 1 Sona (4 interfaces).

Detected Interfaces:
    [1] sona-7C9085C8E6BDAAD1
    [2] sona-8B7B63E05F374C94
    [3] sona-B47277283036FD2F
    [4] sona-1ABAE79791F91419

==> Generated Configuration
    Copy the block between the markers below into your nzyme tap
    configuration file. Channels are split evenly across all interfaces.

---------- BEGIN CONFIGURATION ----------

[wifi_interfaces.sona-7C9085C8E6BDAAD1]
active = true
channels_2g = [1, 2, 3, 4, 5, 6, 7]
channels_5g = []

[wifi_interfaces.sona-8B7B63E05F374C94]
active = true
channels_2g = [8, 9, 10, 11, 12, 13, 14]
channels_5g = []

[wifi_interfaces.sona-B47277283036FD2F]
active = true
channels_2g = []
channels_5g = [36, 40, 44, 48, 52, 56, 60, 64, 100, 104, 108, 112, 116, 120]

[wifi_interfaces.sona-1ABAE79791F91419]
active = true
channels_2g = []
channels_5g = [124, 128, 132, 136, 140, 144, 149, 153, 157, 161, 165, 169, 173, 177]

----------- END CONFIGURATION -----------

[*] Configuration generated for 4 interfaces.

Upgrading Firmware of a Nzyme Device

You need the following to upgrade the firmware of a Nzyme device:

The target Nzyme device connected via USB
The serial number of the target Nzyme device (see nzyme-util devices list above)
The firmware file to flash
Optionally: The SHA256 sum of the Nzyme public key to verifiy firmware and nzyme-util authenticity

You can upgrade the firmware like this:

nzyme-util firmware flash --firmware-file firmware.bin --serial 1ABAE79791F91419

The output will look something like this:

==> Nzyme Firmware Upgrade
    Device Serial : 1ABAE79791F91419
    Firmware File : firmware.bin

Device Information:
    Product        : Sona (802.11/WiFi)
    Manufacturer   : Nzyme LLC
    Serial Number  : 1ABAE79791F91419
    Bootloader     : Sona
    Firmware       : v0.5
    USB VID:PID    : 0x390C:0x0100
    ACM Port       : /dev/ttyACM1

==> Loading Firmware

==> Entering Bootloader Mode
[>] Sending bootloader command over /dev/ttyACM1...
[>] Waiting for bootloader enumeration (0x390C:0x0002)...
[*] Bootloader mode detected.

==> Flashing Firmware
[>] Writing firmware image...
[*] All bytes written. Device is validating and rebooting.

==> Waiting for Device Reboot
[>] Expecting device as 0x390C:0x0100...
[*] Device reconnected.

==> Verifying Firmware Version
[*] New firmware version: v0.5

==> Process complete.

Verifying Authenticity

Public Key Verification

It is critical that you have an authentic copy of the Nzyme public key before verifying releases. You can download the public key from the Nzyme downloads page.

To prevent an attacker from substituting a malicious release and supplying their own key alongside it, always verify your downloaded public key's SHA256 hash against one or more of our trusted, independent sources.

This is the SHA256 hash of the current Nzyme public key:

Key	SHA256
ALPHA	19165ba3a5c92ee306cafcca41e79044cbdafb9daae2dce38838ba0915dead4c

Info

The ALPHA key is used to sign all current Nzyme releases. Additional keys may be introduced in future release channels.

We publish the SHA256 hash of our public keys in the following independent locations:

The download page on www.nzyme.org
The Nzyme GitHub repository README at https://github.com/nzymeorg/nzyme
The DNS TXT record at alpha.keys.nzyme.org
Engraved on physical aluminum tags included with Nzyme hardware purchases

Depending on your security requirements, verify the hash against as many of these sources as needed. The more sources you check, the higher your assurance that the key has not been tampered with.

Verifying on Linux

After downloading the public key, run sha256sum against it and compare the output to the expected hash above and to the DNS TXT record:

sha256sum nzyme-alpha.pub

The hash printed by sha256sum must exactly match both the value in the table above and the DNS TXT record. If there is any discrepancy, do not use the key, discard the downloaded file and contact the Nzyme team.

Verifying Authenticity of `nzyme-util`

We will use nzyme-util to verify authenticity of Nzyme firmware files and software releases. This means that we must ensure that nzyme-util itself is authentic. Using nzyme-util for verification is easy because it can automate the process. However, the initial verification of nzyme-util itself requires openssl.

Step 1: Verify the Public Key

For this verification, we will use the nzyme-alpha.pub.pem key format instead of the standard nzyme-alpha.pub binary distribution.

Confirm that the key sha256sum matches the published hash as described above, using as many factors as your threat model calls for:

$ openssl pkey -pubin -in nzyme-alpha.pub.pem -pubout -outform DER | tail -c 32 | sha256sum

Step 2: Verify `nzyme-util` Using `openssl`

With the public key confirmed as authentic, use openssl to verify the signature of the nzyme-util binary before running it for the first time:

openssl pkeyutl -verify -pubin -inkey nzyme-alpha.pub.pem -rawin -in nzyme-util.deb -sigfile nzyme-util.deb.sig

openssl will print Signature Verified Successfully if the signature is valid. Any other output means the binary has been tampered with or the wrong key was used.

Verifying Authenticity of Software Releases

You can find the required signature file together with the release file on the Nzyme downloads page.

nzyme-util release verify --public-key-file nzyme-alpha.pub --signature-file release.deb.sig --release-file release.deb

Output for an authentic release will look like this:

==> Nzyme Release Signature Verification
    Release File  : release.deb
    Signature File: release.deb.sig
    Public Key    : nzyme-alpha.pub
    File Size     : 61664376 bytes

[✓] Signature VALID — release is authentic and unmodified.

[!!] Verify supplied public key against trusted source:

    19165ba3 a5c92ee3 06cafcca 41e79044
    cbdafb9d aae2dce3 8838ba09 15dead4c

[!!] Additionally, always verify authenticity of this executable as documented.

Verifying Authenticity of Firmware Files

Nzyme firmware files have the signature baked into the release file, and you can run nzyme-util without specifying a separate signature:

nzyme-util firmware verify --public-key-file nzyme-alpha.pub --firmware-file firmware.bin