Skip to main content
Documentation for qso-graph-trust v0.2.1. Source at v0.2.1.

QSO Graph Trust

Latest release qso-graph-trust-cli on crates.io The library's documentation on docs.rs License: GPL-3.0-or-later Platforms: Windows, Linux, macOS

Windows: signed macOS: notarized apt and dnf: GPG signed Provenance: attested, the attestations

QSO Graph Trust signs and uploads your QSOs to ARRL's Logbook of The World (LoTW). It's a security-hardened library and command-line tool written in Rust: your key stays in your computer's credential store, every file it reads is tested against millions of broken and malicious files, and no key data is left in memory it frees.

It's part of the QSO Graph Project, and a ground-up rewrite, not a method-by-method port of TQSL. What it does was decided from the sources below, and how it does it is its own.

Security — Our #1 Priority​

Your key stays in your computer's credential store, leaving it only to sign or into a backup QSO Graph Trust encrypts itself. QSO Graph Trust is built to the standard of enterprise security software, and every point below is a test or a check that runs on every change:

  • OS credential stores only: the macOS Keychain, Windows Credential Manager or the Secret Service on Linux. Never a key file, and never a password or passphrase needed on the command line.
  • Nothing it writes holds your key or a password, and no key data is left in memory it frees. A custody test searches every file, output, log and the program's own memory to prove it.
  • Every file it reads is tested against millions of broken and malicious files (fuzz testing), and every length and count is capped, so a bad file is refused rather than crashing it.
  • Memory-safe Rust: no unsafe code in the library, the command line or anything that parses a file. The one exception is the small binding to AWS-LC, the cryptography library, which is also the only C or C++; policy checks enforce both.
  • Only LoTW, only HTTPS, only ARRL's roots, with the server's certificate always checked.
  • A locked supply chain: pinned dependencies, policy checks and CodeQL on every pull request, and signed, notarized and attested releases.
  • Nothing merges until it passes: over 450 tests, over 2.5 million broken and malicious test files, eight security policy checks, a search of memory and every file written for any trace of a key, and GitHub's CodeQL code scanning, on every change.

How each is tested, and how to report a security problem privately: SECURITY.md.

Sources​

Who it's for​

  • Hams who want to sign and upload their QSOs to LoTW from the command line or their logger, with their key in their computer's credential store.
  • Authors of loggers and tools, who want LoTW signing inside their own program, through the library or the qg-trust command line.

What it does​

qg-trust signs your ADIF (.adi or .adx) or Cabrillo log with your LoTW callsign certificate and uploads it to LoTW, in one command. It brings over everything you have in TQSL from a TQSL backup: certificates, keys, station locations and the record of what you have already signed. It also requests and renews certificates and manages station locations. Loggers that run tqsl can run qg-trust with the same options, exit codes and final status line.

How it's different​

  • Your key stays locked away. It lives in your computer's own credential store (the macOS Keychain, Windows Credential Manager, or the Secret Service on Linux), never as a file someone could copy, and leaves it only to sign.
  • Every QSO is checked by ARRL's own rules before it's signed. A QSO LoTW would refuse is named, with the reason, and the rest are signed. Signatures are byte for byte what TQSL makes.
  • It works inside the program you already use. Another logger or a script can sign and upload for LoTW directly, and the library puts signing inside your own program.
  • It's signed. The macOS program is signed by QSO Graph and notarized by Apple, the Windows program is signed by QSO Graph, and the Linux packages and their repositories are signed with QSO Graph's release key.

Install​

macOS (Apple silicon) and Linux, with Homebrew:

brew install qso-graph/tap/qso-graph-trust

Debian, Ubuntu:

sudo curl -fsSL -o /usr/share/keyrings/qso-graph.gpg https://packages.qso-graph.net/qso-graph.gpg
echo "deb [signed-by=/usr/share/keyrings/qso-graph.gpg] https://packages.qso-graph.net/apt stable main" | sudo tee /etc/apt/sources.list.d/qso-graph.list
sudo apt update && sudo apt install qso-graph-trust

Fedora, RHEL, Rocky:

sudo curl -fsSL -o /etc/yum.repos.d/qso-graph.repo https://packages.qso-graph.net/qso-graph.repo
sudo dnf install qso-graph-trust

Windows: download qg-trust-<version>-windows-x86_64.zip from the latest release and put qg-trust.exe on your PATH. Every release also has the macOS and Linux programs, and SHA256SUMS.txt to check them against.

With Rust: cargo install qso-graph-trust-cli.

Sign and upload a log​

qg-trust import ~/tqsl-backup.tbk     # certificates, keys, locations and your signing record
qg-trust cert list                    # what you have, and when each certificate expires
qg-trust send mylog.adi -l Home       # sign mylog.adi for station location Home and upload it

A key that TQSL protected with a password is asked for once, when you import it, with what you type hidden. send leaves out QSOs you signed before unless you ask, and keeps mylog.tq8 beside the log. qg-trust sign mylog.adi -l Home signs without uploading; qg-trust upload mylog.tq8 uploads it later. To sign only some dates, add -b 2026-01-01 and -e 2026-06-30.

When ARRL starts issuing under a new root, its .tq6 brings the root, and qg-trust import names it with its SHA-256 fingerprint before trusting it: run it again with --trust-root <fingerprint> once you know it is ARRL's. A new root in your own TQSL backup is trusted and named. qg-trust root list shows every root your certificates chain to, and qg-trust root remove <fingerprint> stops trusting one you accepted.

From a logger, the tqsl options work as they are:

qg-trust -x -d -l "Home" -a compliant -u mylog.adi

qg-trust --help lists everything, and the command line's page has every command, option and exit code.

For developers​

The library is qso-graph-trust; its page has an example. To work on QSO Graph Trust itself: CONTRIBUTING.md. What it does and plans, feature by feature: docs/FEATURE-PARITY.md.

Credits​

QSO Graph Trust stands on other people's work.

TrustedQSL (TQSL) and the people who built it and keep it running. TQSL's contributors, as its AUTHORS.txt lists them, are WA1GON, K1MK, KE3Z, K1MU, KC2YWE and AA6YQ, with ARRL. Since 2003 their work has carried the signature on every QSO confirmed through Logbook of The World: a signing format, a certificate system and a program that hams on every platform rely on, kept current through two decades of operating systems, library changes and new modes, as volunteers. Thank you.

ARRL, for LoTW itself and for documenting it for developers.

rfrht's qso-web, a shell script that builds and signs a .tq8 with OpenSSL, without TQSL, and uploads it to LoTW, showing that LoTW accepts a log signed by another program.

License​

GPL-3.0-or-later (LICENSE); see NOTICE.

QSO Graph Trust is not made, affiliated with or endorsed by ARRL. "Logbook of The World," "LoTW," and "TQSL" are ARRL's names, used here only to say what it works with.