qso-graph-trust 0.2.1

Sign ADIF logs for ARRL's Logbook of The World (LoTW)
Documentation

qso-graph-trust

LoTW signing for your own programs: sign ADIF (.adi or .adx) and Cabrillo logs with your LoTW certificate, so ARRL's Logbook of The World (LoTW) accepts them.

  • Memory-safe Rust, with signatures made by AWS-LC, Amazon's open-source cryptography library.
  • Every QSO checked by ARRL's own rules (bands, modes, DXCC entities, dates, satellites) before it is signed; one LoTW would refuse is named, with the field and the reason.
  • The key can only sign: no function returns it, and it is never printed or logged.

It is the library behind the qg-trust command line and QSO Graph Desktop's LoTW signing.

Example

Sign an ADIF log with the certificate in a .tbk file, and write the .tq8 LoTW accepts. The example also uses zeroize and zeroizing-alloc (cargo add zeroize zeroizing-alloc@=0.1.1):

use std::time::SystemTime;

use qso_graph_trust::certificate::Trust;
use qso_graph_trust::qso::Qso;
use qso_graph_trust::signed_log::{sign_log, tq8};
use qso_graph_trust::{records, tbk};
use zeroize::Zeroizing;

// Every program that signs installs a wiping allocator, so no key text is left in memory it frees,
// whichever crate allocated it. QSO Graph Trust's own programs use exactly this one.
#[global_allocator]
static ALLOCATOR: zeroizing_alloc::ZeroAlloc<std::alloc::System> =
    zeroizing_alloc::ZeroAlloc(std::alloc::System);

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // A certificate is trusted only if it chains to LoTW's own root, pinned here.
    let tbk = tbk::read(&std::fs::read("tqslconfig.tbk")?, &Trust::lotw())?;

    let entry = tbk.certificates.iter().find(|c| c.callsign == "K1ABC").ok_or("no certificate")?;
    let certificate = entry.certificate.as_ref().ok_or("no certificate yet")?;
    // Ask for the key's password when the program runs: never on a command line, in a file or in code.
    let password: Zeroizing<Vec<u8>> = ask_for_password()?;
    let key = entry.key.as_ref().ok_or("no key")?.unlock(Some(&password))?;
    let station = &tbk.locations.iter().find(|l| l.name == "Home").ok_or("no location")?.station;

    // Every QSO is checked as LoTW checks it; one it would refuse is an error naming the field.
    let qsos = records::parse(&std::fs::read("log.adi")?)?
        .iter()
        .map(Qso::from_adif)
        .collect::<Result<Vec<_>, _>>()?;

    let signed = sign_log(certificate, &key, station, &qsos, SystemTime::now())?;
    std::fs::write("log.tq8", tq8(&signed))?;
    Ok(())
}
# fn ask_for_password() -> Result<Zeroizing<Vec<u8>>, Box<dyn std::error::Error>> { unimplemented!() }

ask_for_password is your program's: a prompt that does not echo, or the OS's own dialog.

The .tq8 is what LoTW accepts: upload it on LoTW's website.

Checking a download

Each release is published by this repository's release workflow, which GitHub attests: a signed statement that the .crate file was built by that workflow from that commit. With the GitHub CLI:

gh attestation verify qso-graph-trust-<version>.crate -R qso-graph/qso-graph-trust

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.

Sources

QG Trust is a ground-up rewrite in Rust, not a method-by-method port of TQSL. What it does was decided from these, and how is QG Trust's own:

Licence

LoTW's tables are generated from ARRL's TQSL configuration, Copyright (C) 2001-2015 American Radio Relay League, Inc., portions (C) 2003-2026 The TrustedQSL Developers, redistributed under ARRL's terms in LICENSE-ARRL.md (ARRL's text, unchanged), which ships with this crate.

GPL-3.0-or-later. Credits, notices and the source: https://github.com/qso-graph/qso-graph-trust.