Documentation

Related guides

Companion reading for the CLI reference below: how to get up and running, how to plan a PQC rollout for your org, and how to wire QNSQY into existing security tooling.

Installation

Multiple install options: npm (npm install -g qnsqy), the apt or dnf repository, or direct RPM/DEB/Windows .exe download.

Linux

# Download and install to ~/.local/bin
$ mkdir -p ~/.local/bin
$ curl -fsSL https://quantumsequrity.com/downloads/linux/qnsqy-free -o ~/.local/bin/qnsqy
$ chmod +x ~/.local/bin/qnsqy

# Add to PATH (add to ~/.bashrc or ~/.zshrc for permanent)
$ export PATH="$HOME/.local/bin:$PATH"

# Verify installation
$ qnsqy version
QNSQY v7.2.37 (Free)
Post-Quantum: ML-KEM-512, ML-DSA-44
Classical: X25519, Ed25519, AES-256-GCM

Linux - GUI + CLI (Single Binary)

# Download GUI (includes full CLI)
$ mkdir -p ~/.local/bin
$ curl -fsSL https://quantumsequrity.com/downloads/linux/qnsqy-gui-free -o ~/.local/bin/qnsqy-gui
$ chmod +x ~/.local/bin/qnsqy-gui

# Add to PATH
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

# Use as GUI
$ qnsqy-gui

# Use as CLI (same binary!)
$ qnsqy-gui encrypt -i secret.pdf
$ qnsqy-gui decrypt -i secret.pdf.qs
$ qnsqy-gui version

Linux - Package Managers & Other Methods

# Ubuntu / Debian (APT repository)
$ curl -fsSL https://cdn.quantumsequrity.com/repo/qnsqy-repo.gpg.asc | sudo gpg --dearmor -o /usr/share/keyrings/qnsqy.gpg
$ echo "deb [signed-by=/usr/share/keyrings/qnsqy.gpg] https://cdn.quantumsequrity.com/repo/deb stable main" | sudo tee /etc/apt/sources.list.d/qnsqy.list
$ sudo apt update && sudo apt install qnsqy

# Fedora / RHEL / CentOS (DNF repository)
$ sudo tee /etc/yum.repos.d/qnsqy.repo <<'EOF'
[qnsqy]
name=QNSQY
baseurl=https://cdn.quantumsequrity.com/repo/rpm
enabled=1
gpgcheck=0
repo_gpgcheck=1
gpgkey=https://cdn.quantumsequrity.com/repo/qnsqy-repo.gpg.asc
EOF
$ sudo dnf install qnsqy

# npm (wrapper package, installs the same binary)
$ npm install -g qnsqy

Make it Permanent

# For bash users
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
$ source ~/.bashrc

# For zsh users
$ echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
$ source ~/.zshrc

# Now works from anywhere
$ qnsqy encrypt -i secret.pdf       # if CLI installed
$ qnsqy-gui encrypt -i secret.pdf   # if GUI installed

Windows - CLI Only (PowerShell)

# Download to user's local bin
> mkdir -Force "$env:USERPROFILE\.local\bin"
> Invoke-WebRequest -Uri "https://quantumsequrity.com/downloads/windows/qnsqy-free.exe" -OutFile "$env:USERPROFILE\.local\bin\qnsqy.exe"

# Add to PATH for current session
> $env:PATH = "$env:USERPROFILE\.local\bin;$env:PATH"

# Add to PATH permanently
> [Environment]::SetEnvironmentVariable("PATH", "$env:USERPROFILE\.local\bin;$([Environment]::GetEnvironmentVariable('PATH', 'User'))", "User")

# Verify installation (restart terminal first)
> qnsqy version

Windows - GUI + CLI (Single Binary)

# Download GUI (includes full CLI)
> mkdir -Force "$env:USERPROFILE\.local\bin"
> Invoke-WebRequest -Uri "https://quantumsequrity.com/downloads/windows/qnsqy-gui-free.exe" -OutFile "$env:USERPROFILE\.local\bin\qnsqy-gui.exe"

# Add to PATH permanently
> [Environment]::SetEnvironmentVariable("PATH", "$env:USERPROFILE\.local\bin;$([Environment]::GetEnvironmentVariable('PATH', 'User'))", "User")

# Restart terminal, then use as GUI
> qnsqy-gui

# Or use as CLI (same binary!)
> qnsqy-gui encrypt -i secret.pdf --acknowledge-no-sandbox
> qnsqy-gui version

Binary Name

All tiers use a single binary:

Encrypted files use the .qs extension. Command availability depends on your active license tier.

Global Options

These options are available for all commands:

Quick Start

# Encrypt a file
$ qnsqy encrypt -i secret.pdf
# Output: secret.pdf.qs

# Decrypt a file
$ qnsqy decrypt -i secret.pdf.qs
# Output: secret.pdf

# Securely delete original
$ qnsqy shred secret.pdf
# File overwritten and deleted

Remote Backup (Cloud): All Tiers

QNSQY can encrypt your data on your computer and upload only the encrypted result to your own cloud storage bucket. The cloud provider never sees your files, your file names, or your keys, just opaque encrypted blobs. This works on every tier (Free included). Supported storage: Cloudflare R2 (default), AWS S3, Google Cloud Storage, MinIO or your own server, Backblaze B2, and Wasabi.

You need three things before you start: (1) a storage bucket you created in your provider's console, QNSQY never creates buckets for you; (2) an access key + secret for that bucket with read and write permission; (3) the bucket's endpoint URL and region (see the table below).

Step 1: Create the bucket and an access key

In your provider's console, create a bucket, then create an access key (also called an "API token" or "HMAC key"). Give that key read + write on that one bucket, nothing more. In plain terms it needs to List, Get, and Put objects. You do not need delete, admin, or account-wide permission. A read-only key is not enough: it will pass the connection test but fail the first upload.

Step 2: Find your endpoint, region, and addressing

Notes: for AWS only, turn on "virtual-host addressing" (it is off for every other provider). Your own server (MinIO) must use HTTPS with a publicly valid certificate. Plain HTTP and self-signed certificates are rejected on purpose. If a push fails with "SignatureDoesNotMatch", the Region is wrong; if it fails with "NoSuchBucket", create the bucket first.

Step 3: Give QNSQY your credentials

Your secret is never written to disk by QNSQY and never passed on the command line. Provide it one of three ways:

# Easiest: environment variables (this terminal session)
$ export QNSQY_REMOTE_ACCESS_KEY=your-access-key-id
$ export QNSQY_REMOTE_SECRET=your-secret-access-key
# AWS temporary (STS) credentials also need:
#   export QNSQY_REMOTE_SESSION_TOKEN=your-session-token
# In the GUI: just type the Access key and Secret into the panel fields.
# Or store them in the PQC Vault (Pro): --creds-vault <vault> --creds-entry <name>

Step 4: Back up and restore (example: Cloudflare R2)

# 1. Save the destination once (or skip and use --endpoint/--bucket each time)
$ qnsqy remote add r2 --endpoint https://<account-id>.r2.cloudflarestorage.com --bucket my-backups --region auto

# 2. Check it works (one read-only test request)
$ qnsqy remote test --remote r2

# 3. Encrypt locally and upload only ciphertext
$ qnsqy push -i ./Documents --remote r2

# 4. Restore later (verifies the signed manifest + every hash before decrypting)
$ qnsqy pull --remote r2 -o ./restored

# Without a saved profile, pass the destination inline instead of --remote r2:
#   qnsqy push -i ./Documents --endpoint https://<account-id>.r2.cloudflarestorage.com --bucket my-backups

Restore options: --generation N restores a specific older snapshot, --verify-only checks integrity without writing files, and --key <private-key> restores a backup that was encrypted to a recipient key. In the GUI, the same controls live on the Remote Backup page in the sidebar and as panels on the Encrypt, Decrypt, and Batch pages.

Important: the cloud copy is encrypted and cannot be recovered without your password or key. If you lose both, the backup is gone. Pair remote backup with escrow, threshold shares, or multi-recipient keys for recovery.

Commands by Tier

Command availability depends on your license tier:

Organizations and Teams

Business-tier teams can be managed as an organization: one owner, any number of members, shared governance, and a single audited place to provision people. Organizations and the controls below are a Business feature; Free and Pro accounts are always individual.

Roles

• Owner: the person an organization is created around. Full control of the organization.
• Admin: can manage members and organization settings.
• Member: a standard team member covered by the organization's tier and policy.

A person belongs to one organization at a time. To move someone between organizations, remove them from the first one before adding them to the second.

Adding people

An administrator creates accounts and brings people into an organization from the admin dashboard. When someone new is added:

• They receive a one-time sign-in link by email, valid for 72 hours.
• The link never contains a password. The new person signs in with the link, then sets their own password from their dashboard.
• Existing QNSQY users are added to the organization directly, without a new account.

Single sign-on (SSO)

Each organization can connect its own identity provider so members sign in with corporate credentials. QNSQY supports OpenID Connect (OIDC) and SAML 2.0. SSO is configured, and can be tested before rollout, from the organization admin portal. A device-code flow is available so the CLI can authenticate through your provider as well.

Organization encryption policy

An organization can publish a signed encryption policy that sets minimum cryptographic requirements for its members, for example a minimum algorithm strength or a requirement to use post-quantum protection. The policy is signed (Ed25519) so it cannot be tampered with in transit, and the QNSQY client fetches and enforces it at runtime: an operation that would fall below the policy is refused locally. This is how a team keeps its quantum-safe standard consistent across everyone's data, not just one person's.

Audit log

Organization-level actions (members added or removed, roles changed, policy and SSO updates) are recorded in a per-organization audit log that owners and admins can review.

Manage all of the above from the organization admin portal at quantumsequrity.com/org-admin. For a rollout plan, see Implementing PQC in your organization.

Command Reference

Pro+ & Business Commands

These commands require a Pro or Business license. Some commands are Business-only (see tier badge).

Utility Commands (All Tiers)

Available on all tiers including Free.

Usage Examples

Basic Encryption Workflow

# Encrypt a document
$ qnsqy encrypt -i contract.pdf
Enter password: ********
Confirm password: ********
✓ Encrypted: contract.pdf.qs

# Securely delete the original
$ qnsqy shred contract.pdf
⚠ This will permanently destroy: contract.pdf
Confirm? [y/N]: y
✓ Securely deleted: contract.pdf

# Later: decrypt when needed
$ qnsqy decrypt -i contract.pdf.qs
Enter password: ********
✓ Decrypted: contract.pdf

Encrypting with Compression

# Large text-based files compress well with zstd
$ qnsqy encrypt -i database.sql -z
Enter password: ********
Confirm password: ********
⟳ Compressing with zstd...
⟳ Encrypting with AES-256-GCM...
✓ Encrypted: database.sql.qs

Recipient-Based Encryption (Password-less)

# Alice: Generate encryption keypair
$ qnsqy keygen-enc -o alice_key -n "Alice"
✓ Private key: alice_key
✓ Public key: alice_key.pub

# Alice shares alice_key.pub with Bob

# Bob: Encrypt file for Alice (no password needed)
$ qnsqy encrypt -i secret.pdf --recipient alice_key.pub
✓ Encrypted: secret.pdf.qs

# Alice: Decrypt using her private key
$ qnsqy decrypt -i secret.pdf.qs --key alice_key
✓ Decrypted: secret.pdf

Hybrid Encryption (Key + Password)

# Encrypt requiring BOTH key AND password
$ qnsqy encrypt -i top-secret.pdf --recipient alice_key.pub --hybrid
Enter password: ********
Confirm password: ********
✓ Encrypted: top-secret.pdf.qs

# Decrypt requires both private key AND password
$ qnsqy decrypt -i top-secret.pdf.qs --key alice_key
Enter password: ********
✓ Decrypted: top-secret.pdf

Signing Keypairs

# Generate a signing keypair (ML-DSA-87 = NIST Level 5, Pro+)
$ qnsqy keygen-sign -o mykey -n "My Signing Key" --algorithm ml-dsa87
⟳ Generating ML-DSA-87 keypair...
✓ Private key: mykey
✓ Public key: mykey.pub

# Free tier: ML-DSA-44 only
$ qnsqy keygen-sign -o mykey -n "My Key"
✓ Private key: mykey (ML-DSA-44)
✓ Public key: mykey.pub

Signing & Verification

# Sign a release artifact
$ qnsqy sign -i release.tar.gz -k mykey
Enter password: ********
✓ Signed: release.tar.gz.sig

# Verify a signed file (signature auto-detected from .qsig)
$ qnsqy verify -i release.tar.gz -k author.pub
✓ Signature valid (ML-DSA-87)

Custom Argon2 Parameters (Business)

# Maximum security: 1GB memory, 10 iterations
$ qnsqy encrypt -i secrets.tar \
    --argon2-memory 1048576 \
    --argon2-iterations 10 \
    --argon2-parallelism 8

# Use XChaCha20-Poly1305 cipher (all tiers)
$ qnsqy encrypt -i data.bin --algorithm xchacha20-poly1305

# Change password without re-encryption (Pro+)
$ qnsqy rekey -f secrets.tar.qs
Enter current password: ********
Enter new password: ********
Confirm new password: ********
✓ Password changed.

Batch Operations (Pro+)

# Encrypt multiple files in parallel
$ qnsqy batch encrypt *.pdf -o ./encrypted/ -j 4
Enter password: ********
✓ Encrypted 15 files (4 parallel jobs)

# Decrypt with signature verification
$ qnsqy batch decrypt ./encrypted/*.qs --verify-key author.pub
Enter password: ********
✓ Decrypted and verified 15 files

# Decrypt with recipient private key (public-key encryption)
$ qnsqy batch decrypt ./encrypted/*.qs --key mykey
✓ Decrypted 15 files using recipient key

Secret Sharing (Business)

# Split a secret into 5 shares, need 3 to recover (3-of-5)
$ qnsqy split -i master-key.txt -m 3 -n 5
✓ Created 5 shares: master-key.txt.share1 ... master-key.txt.share5

# Distribute shares to different locations/people

# Later: Recover with any 3 shares
$ qnsqy combine -o recovered.txt -m 3 share1 share3 share5
✓ Recovered: recovered.txt

View Audit Log (Pro+)

# View all operations
$ qnsqy audit
2025-01-15 09:23:41  ENCRYPT  contract.pdf
2025-01-15 09:24:02  SHRED    contract.pdf
2025-01-15 14:30:11  DECRYPT  contract.pdf.qs

# View only security events, export to file
$ qnsqy audit --security-only --export audit-report.json

# Verify audit log integrity
$ qnsqy audit --verify
✓ Audit log integrity verified (hash chain intact)

Argon2id Presets

Password-based key derivation uses Argon2id with configurable security presets:

Use --argon2-preset <standard|high|maximum> to select a preset. Business users can override with custom values using --argon2-memory, --argon2-iterations, and --argon2-parallelism flags.

File Size Limits

Maximum file size varies by tier:

File Format

Encrypted files use the .qs extension. Magic bytes QNS6 at offset 0; current wire format version 6.1. v6.0 files continue to decrypt with this binary via the backward-compat path; the reader auto-detects the on-disk minor version. Full byte-level layout in the QNSQY (.qs) format specification.

The format is split between a 128-byte plaintext fixed header and an AEAD-encrypted header. The plaintext fixed header carries everything the parser needs before the encrypted header can be opened: magic, version, algorithm tags (KEM, AEAD, KDF, hash, compression), Argon2id salt and parameters, BLAKE3 key commitment, encrypted-header length, plaintext file size, and three parser-essential public flag bits. The encrypted header carries the rest:

• Format version identifier (major 6, minor 0 or 1)
• Argon2id parameters (salt, memory, iterations, parallelism)
• Hybrid ML-KEM + X25519 encapsulated key (ML-KEM-512/768/1024 or HQC)
• AES-256-GCM or XChaCha20-Poly1305 nonce
• Encrypted data with AEAD authentication tag
• BLAKE3 integrity hash (so verify-integrity can detect corruption without the decryption key)
• v6.1 sealed metadata: tier byte and six private flag bits (HSM-wrapped, escrow, directory archive, integrity, keyfile-derived, ABE) live inside the AEAD-encrypted header so a passive observer with only file access does not learn the producing tier or which optional features were used.

Files encrypted with any tier can be decrypted by any other tier. The format is forward-compatible. Two intentional residual fingerprints remain on disk by design: the integrity-presence indicator at reserved[24] == 0x01 (so corruption checks work without the password), and the plaintext QSEC magic of the optional escrow trailer at end-of-file (so escrow-recovery tooling can find the trailer without the password). Operators who need escrow usage hidden must not use the escrow feature.

IANA media type registration (application/vnd.quantumsequrity.qnsqy) is drafted per RFC 6838 §5.6 vendor tree; submission to IANA is in progress. Until provisional acceptance lands, the type string is a vendor-tree identifier under our control but is not yet IANA-listed.

NIST ACVP Test Vector Validation

QNSQY ships with a test harness at qs-ultra/tests/acvp_official/ that replays the full ACVP-Server v1.1.0.42 vector tree (commit 15c0f3deeefbfa) against the same Rust crates QNSQY ships (sha2, sha3, hmac, aes-gcm, ed25519-dalek, x25519-dalek, ml-kem, ml-dsa, slh-dsa). Each ACVP vector is loaded from NIST's JSON, run through the production crate, and the output is matched byte-for-byte against NIST's expectedResults.json.

As of the 2026-07-31 sweep (wall-clock 439.15 s on a Fedora 44 workstation): 18,703 vectors passed, 0 failures, 11,259 skipped (unimplemented parameter sets, e.g. RSA, ECDSA, AES-CBC), 29,962 total vectors in the NIST ACVP-Server v1.1.0.42 reference tree. 33 of 50 ACVP algorithm directories are at 100% NIST coverage.

Per-family pass counts

Reproduce locally

QNSQY's product source is closed, but the test harness is fully shareable: it depends only on public RustCrypto crates and contains no QNSQY proprietary code. We publish it as a self-contained archive on the Validation page, with full step-by-step instructions. Source access for customers and auditors is available on request under NDA.

# Download the standalone reproducer harness (no QNSQY product code required)
$ curl -fLO https://quantumsequrity.com/validation-artifacts/qnsqy-acvp-harness-v1.0.tar.gz
$ curl -fLO https://quantumsequrity.com/validation-artifacts/qnsqy-acvp-harness-v1.0.tar.gz.sha256
$ sha256sum -c qnsqy-acvp-harness-v1.0.tar.gz.sha256
$ tar xzf qnsqy-acvp-harness-v1.0.tar.gz && cd qnsqy-acvp-harness

# Stage NIST's public ACVP-Server vector tree per the README, then run the replay
$ cargo build --release --tests
$ ./target/release/deps/acvp_official-* --nocapture --test-threads 2

Documented skips fall into two buckets. (1) NIST vectors outside QNSQY's scope: RSA, ECDSA, AES-CBC/CTR/CCM/XTS/KW, KMAC, CMAC, KDF-TLS/SSH/IKE, DRBG, KAS-ECC/FFC/IFC, AES-192, Ed25519ph, Ed448, SP 800-56C TwoStep. (2) Upstream Rust crate API limits: ml-dsa 0.1.0-rc.7 keeps raw_sign_mu(mu, rnd) private so 45 ML-DSA externalMu randomized vectors are blocked; ml-kem 0.2.3 does not expose encapsulationKeyCheck / decapsulationKeyCheck; bit-oriented SHA/SHAKE inputs require sub-byte state machinery not built in this revision. Production source is untouched: the only repository delta is three test-only [dev-dependencies] in qs-ultra/Cargo.toml (sha1, ml-kem with deterministic, hybrid-array).

Background on the harness, methodology, and per-vector log is in the NIST ACVP validation write-up.

Common Error Messages