NAME

noqtis — post-quantum signatures, KEMs and sealed capsules of files

SYNOPSIS

noqtis command [options] [args]

noqtis -h | --help

noqtis -V | --version

noqtis help [command]

DESCRIPTION

noqtis records the exact files a result came from, signs that record with a post-quantum signature (ML-DSA, FIPS 204, or SLH-DSA, FIPS 205) and checks such records later. It also signs and verifies single files, runs the ML-KEM (FIPS 203) and HQC key encapsulation mechanisms, and prints and checks file digests. It is a thin tool over the public C interface of noqtis(3) and calls nothing else.

The commands are:

keygen: Make a key pair. See noqtis-keygen(1).
sign: Sign a file. See noqtis-sign(1).
verify: Check a signature. See noqtis-verify(1).
enc: Encapsulate a shared secret to a KEM public key. See noqtis-enc(1).
dec: Decapsulate a shared secret with a KEM secret key. See noqtis-dec(1).
hash: Print or check file digests in the format of sha256sum(1). See noqtis-hash(1).
seal: Seal a folder: write noqtis.json and noqtis.sig into it. See noqtis-seal(1).
check: Check a sealed folder against its seal. See noqtis-check(1).
prove: Prove that some files are in a format 2 capsule, without the others. See noqtis-prove(1).
export: The capsule as in-toto (signed in DSSE), RO-Crate or BagIt. See noqtis-export(1).
rotate, revoke: Say that a seal key was replaced, or must no longer be trusted, for check --keys. See noqtis-rotate(1) and noqtis-revoke(1).
idcard: Make or check an identity card: a signing key with its holder's name, ORCID iD, e-mail address, web page and affiliation, signed by the key, for check --card. See noqtis-idcard(1).
timestamp: Add an RFC 3161 timestamp to a folder sealed before. See noqtis-timestamp(1).
inspect: Show what a sealed folder says (format, algorithm, key fingerprint, created, files, size, timestamp, meta) without checking it. See noqtis-inspect(1).
algs: List every algorithm and its sizes. See noqtis-algs(1).
version: Print the version. See noqtis-version(1).
help [command]: Print the list of commands, or the options of one command.

Options follow the command. A short option takes its value as the next argument or joined to it (-kkey); a long option takes it as the next argument or after ‘=’ (--key=key). -h or --help after any command prints its usage. -- ends the options; an argument ‘-’ alone is a positional argument (standard input where a command allows it).

Algorithm names

Algorithms are named as noqtis algs prints them, without regard to case: ML-DSA-44, ML-DSA-65, ML-DSA-87, SLH-DSA-SHA2-128s, SLH-DSA-SHA2-128f, SLH-DSA-SHA2-192s, SLH-DSA-SHA2-192f, SLH-DSA-SHA2-256s, SLH-DSA-SHA2-256f, SLH-DSA-SHAKE-128s, SLH-DSA-SHAKE-128f, SLH-DSA-SHAKE-192s, SLH-DSA-SHAKE-192f, SLH-DSA-SHAKE-256s, SLH-DSA-SHAKE-256f, ML-DSA-44+Ed25519, ML-DSA-65+Ed25519, ML-DSA-87+Ed25519 (post-quantum signatures, the last three hybrid), Ed25519 (classical, not for seals) and ML-KEM-512, ML-KEM-768, ML-KEM-1024, HQC-128, HQC-192, HQC-256 (key encapsulation).

Key files

A key file is text: one header line, then the key bytes in the standard's own encoding (FIPS 203, 204, 205; HQC v5.0.0) as base64 (RFC 4648, with padding) in lines of 64 characters:

noqtis-key-1 <algorithm> <pub|sec>
<base64>
...

Readers accept ‘\n’ or ‘\r\n’ line ends and reject any other character, non-canonical padding, a header that is not exactly three space-separated fields, the wrong kind of key (‘pub’ where a secret key is needed, or the reverse), and a key whose decoded length is not the algorithm's size. The base64 encoder and decoder run in constant time.

Signatures and ciphertexts are raw bytes in the standard's encoding, with no header. A shared secret file holds the raw 32 bytes.

Secrets and files

Secret key and shared-secret files are created owner-only (mode 0600, with O_EXCL | O_NOFOLLOW on POSIX; on Windows they inherit the folder's ACL) through unbuffered streams. No command overwrites an existing file unless given --force; with it the old file is removed first, so the new one never inherits its permissions or follows a link. Every buffer that held a secret key, seed or shared secret is wiped before it is freed. No secret is printed: a shared secret reaches standard output only with --stdout (in hex), and keys never do.

On Windows, arguments are read as UTF-16 and passed on as UTF-8, and standard input and output are in binary mode.

EXIT STATUS

For every command:

0: Success: a signature is valid, every capsule check passed, every digest matched.
1: A verification failed: a bad or wrong-length signature, a failed capsule check, a digest that differs or a listed file that is missing, a malformed --check line.
2: A usage error, an unreadable or unwritable file, the wrong kind of key, or a library error.

EXAMPLES

Seal a folder, check it, change a file and check again:

$ noqtis keygen -a ML-DSA-65 -o me
ML-DSA-65 key pair: me (secret), me.pub (public)
$ noqtis seal -k me results
sealed results with ML-DSA-65
$ noqtis check -p me.pub results
...
results: OK (22 checks passed)
$ echo extra >> results/report.txt
$ noqtis check -p me.pub results; echo $?
...
FAIL  file                report.txt: size differs
...
results: FAILED (1 of 22 checks failed)
1

STANDARDS

FIPS 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard, NIST, August 2024. FIPS 204: Module-Lattice-Based Digital Signature Standard, NIST, August 2024. FIPS 205: Stateless Hash-Based Digital Signature Standard, NIST, August 2024. Hamming Quasi-Cyclic (HQC), version 5.0.0, August 2025.

CAVEATS

noqtis has not had an external security audit.

noqtis(1)