What This Guide Covers
This is a step-by-step tutorial for people who have never used QNSQY before. By the end, you will know how to:
- Install QNSQY on Linux or Windows
- Encrypt a file so that only someone with the password can read it
- Decrypt a file to get the original back
- Generate signing and encryption keys
- Sign a file to prove it came from you and has not been changed
- Verify a signature to confirm a file is authentic
- Securely delete a file, and what that can and cannot guarantee
- Read a .qs file's metadata and what each field means
No prior cryptography knowledge is required. The commands and messages below come from the current release on the Free plan, which needs no account. Other versions may word some messages differently.
Step 1: Install QNSQY
QNSQY runs on Linux and Windows on 64-bit x86 (x86_64) computers. There is no macOS or ARM build.
Linux
The quickest way is the install script. It downloads the .deb or .rpm package for your distribution, checks it against the published SHA-256 list, and installs it with your package manager:
curl -fsSL https://quantumsequrity.com/downloads/install.sh | bashIt is a good habit to read a script before you run it:
curl -fsSL https://quantumsequrity.com/downloads/install.sh -o install.sh
less install.sh
bash install.shYou can also add the QNSQY package repository (apt or dnf), so updates arrive with your normal system updates, or install a package by hand. The download page has the exact commands for each.
Windows
Download the installer (.exe) from the download page and run it. It installs QNSQY in C:\Program Files\QNSQY and adds qnsqy to the system PATH, so you can use it from Command Prompt or PowerShell. Open a new window after installing.
Check the Installation
Open a terminal (on Windows, Command Prompt or PowerShell) and type:
qnsqy versionYou should see something like this:
QNSQY <version>
Tier: Free
Use 'qnsqy version --verbose' for algorithm and feature details."Tier" is your plan. Without an account it is Free, which is all this guide needs.
Step 2: Encrypt Your First File
Encryption turns a readable file into scrambled data that only someone with the correct password can unscramble. Think of a safe: anyone can see that it exists, but nobody can read what is inside without the combination.
First, create a test file with some text in it:
echo "This is my secret message" > secret.txtNow encrypt it:
qnsqy encrypt -i secret.txtQNSQY asks for a password twice. Nothing appears on screen while you type; that is deliberate:
Password:
Confirm password:
Encrypted to: secret.txt.qsIf the password is short, QNSQY warns you and suggests 12 or more characters. A long passphrase of several random words is both strong and easy to type.
On Linux you will also see one or two lines that start with SECURITY|, such as SECURITY|sandbox_applied|phase=1|enforced=true|.... That is QNSQY reporting that its sandbox is on and, for the operation itself, that network access is blocked. These lines are normal.
You now have two files: the original secret.txt and the encrypted secret.txt.qs. If you open the .qs file in a text editor, you will see random-looking bytes. That is exactly what you want.
What Happened Behind the Scenes
- Your password was stretched with Argon2id. Argon2id (specified in RFC 9106) is deliberately slow and memory-hungry. By default QNSQY uses 128 MB of memory and 3 passes, so each password guess needs the same 128 MB and 3 passes, which makes guessing at scale slow and expensive.
- A one-time post-quantum key pair was made for this file. QNSQY created a new ML-KEM-512 + X25519 key pair, locked its private key with a key derived from your password, and mixed the key-exchange secret with your password secret to make the key that encrypts the file. ML-KEM is the NIST standard FIPS 203; X25519 is a widely used classical algorithm.
- The contents were encrypted with AES-256-GCM. This is authenticated encryption (NIST SP 800-38D): it hides the data and detects any change to it.
- Integrity checks tie it together. With the default settings, a BLAKE3 hash tree links the encrypted pieces in order and a keyed BLAKE3 check protects the header, so a damaged, altered or reordered file is refused instead of giving you wrong data.
One honest point: in a password-only file, the password is still what protects it. Anyone who knows it, or guesses it, can open the file. Use a long, unique passphrase and keep it in a password manager.
Step 3: Decrypt a File
Decryption reverses the process. QNSQY never overwrites an existing file unless you add -f, and secret.txt is still there, so write the result to a new name with -o:
qnsqy decrypt -i secret.txt.qs -o restored.txtEnter your password when asked:
Password:
Decrypted to: restored.txt
Open restored.txt: it matches the original. Without -o, QNSQY writes secret.txt, and stops with "Output file already exists - use --force to overwrite" if that file is still there.
If you enter the wrong password, QNSQY tells you and writes nothing:
Error: Wrong password or corrupted fileQNSQY also slows down repeated wrong guesses on the same computer. After 9 wrong passwords within 5 minutes, each further wrong try waits longer (2, 4, 8 seconds and so on, up to 60 seconds). It never locks you out of your own file. This only slows guessing through QNSQY itself: someone who copies the .qs file can try passwords with their own tools, which is why the Argon2id cost and a strong passphrase matter.
Step 4: Generate Signing and Encryption Keys
Passwords are one way to protect files. Keys are another. A password is like a combination lock where both sides know the code. A key pair is like a mailbox: anyone can drop a letter in (using your public key), but only you can open it (using your private key).
QNSQY uses two kinds of key pairs: signing keys, which prove that a file is authentic, and encryption keys, which let other people encrypt files to you.
Generate a Signing Key Pair
Signing keys let you attach a digital signature to a file. The signature proves two things: the file came from the holder of the private key, and nobody has changed it since it was signed.
qnsqy keygen-sign -o mykey -n "Alice Signing Key"QNSQY first asks for a passphrase to protect the private key. Use one: if you just press Enter, the private key is saved unencrypted. Then it reports what it made:
Enter passphrase to protect private key (or press Enter for no passphrase):
Confirm passphrase:
SUCCESS: Generated signing keypair for "Alice Signing Key"
Generated keypair for "Alice Signing Key":
Algorithm: ML-DSA-44
Private key: mykey (encrypted)
Public key: mykey.pub
This creates mykey, your private key (keep it secret), and mykey.pub, your public key (safe to share). On the Free plan the signature algorithm is ML-DSA-44 (NIST FIPS 204). Pro and Business add ML-DSA-65 and ML-DSA-87, SLH-DSA (FIPS 205) and hybrid signatures with Ed25519, chosen with --algorithm.
Generate an Encryption Key Pair
Encryption keys let someone encrypt a file specifically for you, without sharing a password:
qnsqy keygen-enc -o myenc -n "Alice Encryption Key"After the same passphrase questions, QNSQY shows:
SUCCESS: Generated encryption keypair for "Alice Encryption Key"
Generated encryption keypair for "Alice Encryption Key" (ML-KEM-512 + X25519):
Private key: myenc (encrypted)
Public key: myenc.pub (share with others)
Usage:
Others encrypt to you: qnsqy encrypt -i file.txt --recipient myenc.pub
You decrypt: qnsqy decrypt -i file.txt.qs --key myenc
Share myenc.pub with anyone who wants to send you encrypted files. Only your private key, myenc, can decrypt what they send.
Step 5: Sign a File
Signing does not encrypt a file or hide its contents. It attaches a mathematical proof that the holder of the private key approved this exact file, like a notary's stamp: everyone can still read the document, but the stamp shows it is authentic and unaltered.
qnsqy sign -i report.pdf -k mykeyQNSQY asks for the private key's passphrase, then signs:
Enter passphrase to unlock private key:
Signing: report.pdf
Using: ML-DSA-44
File signed successfully.
Signature appended to: report.pdf
By default QNSQY adds the signature to the end of the file itself instead of writing a separate signature file: the original content stays as it was, followed by the signature. The file is therefore no longer byte-for-byte the original, so if it must stay identical, sign a copy. To let others check it, send the signed file together with your public key, mykey.pub.
Step 6: Verify a Signature
When you receive a signed file, check it with the sender's public key:
qnsqy verify -i report.pdf -k alice.pubIf the signature is valid:
Verifying: report.pdf
Signature VALID
Algorithm: ML-DSA-44
Key hash: (16 hexadecimal characters that identify the key)If the file was changed after signing, even by a single bit, or was signed with a different key:
Verifying: report.pdf
Signature INVALID!
The file may have been tampered with or signed with a different key.A valid signature proves the file matches the public key you used, so get that key from the sender through a channel you trust, for example by comparing the key hash over the phone. This matters for software, legal documents, medical records and anything else where you need proof that a file has not been altered.
Step 7: Securely Delete Files
When you delete a file normally (moving it to the Recycle Bin on Windows, or running rm on Linux), the data is not actually erased. The operating system marks that space as free, and until something else overwrites it, forensic tools can often recover the data.
Think of tearing the table of contents out of a book: the chapters are still there, and someone patient can still read every page.
QNSQY's shred command overwrites the file's data before deleting it:
qnsqy shred secret.txt -f
Without -f, QNSQY asks you to confirm first. Output:
Shredding with 3 passes...
Securely deleted: secret.txt
By default QNSQY overwrites the file three times (zeros, then ones, then random bytes), then empties it, renames it to a random name and deletes it. -p sets a different number of passes.
Overwriting works best on traditional spinning hard drives. On SSDs and copy-on-write file systems, old copies of the data can survive where no overwrite reaches (wear leveling, snapshots). QNSQY warns you when it detects an SSD or a copy-on-write file system, or cannot tell what kind of drive it is. On those drives, treat shredding as best effort and use full-disk encryption from day one.
A common workflow is to encrypt a file and then shred the original:
qnsqy encrypt -i secret.txt && qnsqy shred secret.txt -f
The && runs the shred only if the encryption succeeded, so only the encrypted copy remains. It works in Linux shells, Command Prompt and PowerShell 7; in older Windows PowerShell, run the two commands one after the other.
Understanding the .qs File Format
Every .qs file starts with a header that describes how it was encrypted. You can read it without the password:
qnsqy decrypt --show-metadata -i secret.txt.qsOutput from the current release:
File metadata for: secret.txt.qs
WARNING: These values are UNAUTHENTICATED, read from the unencrypted
fixed header BEFORE MAC verification. An attacker could have spoofed any
of these fields (including Argon2 parameters). Do NOT trust them for
security decisions. Decrypt the file to verify authenticity.
╔═══════════════════════════════════════════════════════════╗
║ FILE METADATA ║
╠═══════════════════════════════════════════════════════════╣
║ Format Version: 6.1 ║
║ Tier: (sealed - decrypt to view) ║
║ Original Size: 26 bytes ║
║ AEAD Algorithm: Aes256Gcm ║
║ KEM Algorithm: MlKem512X25519Hybrid ║
║ Compression: None ║
║ Encryption Mode: Password Only ║
║ Argon2 Memory: 131072 KB (128 MB) ║
║ Argon2 Iterations: 3 ║
║ Argon2 Parallelism:4 ║
╚═══════════════════════════════════════════════════════════╝As the warning says, these values come from the unencrypted part of the file, before any integrity check, so treat them as a hint and decrypt to confirm. What each field means:
- Format Version: the version of the .qs file layout (6.1 in the current release).
- Tier: the plan of the account that made the file. Since format 6.1 it is stored inside the encrypted part, so it shows only after decrypting. It matters for opening the file: see the note below.
- Original Size: the size of the file before encryption. The encrypted file is slightly larger because of the header and the integrity checks.
- AEAD Algorithm: the cipher for the contents. AES-256-GCM is the default; XChaCha20-Poly1305 is available on every plan.
- KEM Algorithm: the key exchange. MlKem512X25519Hybrid means ML-KEM-512 combined with X25519. ML-KEM-768 and ML-KEM-1024 need Pro or Business.
- Compression: whether the data was compressed before encryption.
- Encryption Mode: "Password Only" means a password protects the file. Other modes use a recipient's public key.
- Argon2 Memory, Iterations, Parallelism: the password-stretching settings. The default uses 128 MB; Pro and Business can choose 256 MB, and Business 512 MB.
A note on plans: In the current release, each file records the plan of the account that made it, and QNSQY opens the file only on that plan or a higher one. A file made while signed in to Pro opens on Pro or Business; a file made on Business opens only on Business; a file made on Free, or while signed out, opens on every plan. So if a paid plan ends, or a paid computer stays offline for more than 7 days without checking in, QNSQY works as Free until you renew or reconnect, and files made on the paid plan cannot be opened until then.
Common Options Explained
Compress Before Encrypting
For text files, documents and other compressible data, -z compresses the data with zstd before encryption, which can make the encrypted file much smaller:
qnsqy encrypt -i database_dump.sql -z
Skip -z for files that are already compressed (MP4 video, JPEG images, ZIP archives): compressing them again costs time and saves little or nothing.
Custom Output Location
By default the encrypted file goes next to the original with .qs added to its name. To write it somewhere else:
qnsqy encrypt -i secret.txt -o /mnt/usb/encrypted_secret.qsEncrypt to a Recipient's Public Key
Instead of a password, you can encrypt with someone's public encryption key, so only the holder of the matching private key can decrypt it:
qnsqy encrypt -i report.pdf --recipient bob_enc.pubBob then decrypts with his private key:
qnsqy decrypt -i report.pdf.qs --key bob_encThis lets you send encrypted files without sharing a password. The Free plan encrypts to one recipient per file; Pro and Business can encrypt one file to several recipients. Remember the plan note above: in the current release, Bob needs your plan or a higher one to open a file you made while signed in to a paid plan.
Hash a File
A hash is a fingerprint of a file: if even one bit changes, the hash changes completely. It is useful for checking a file after a download or a transfer:
qnsqy hash -i report.pdf
QNSQY prints the BLAKE3 hash (64 hexadecimal characters) followed by the file name. -a chooses another algorithm, such as SHA-256, SHA-512 or SHA3-256. Later, check the file against the hash you saved:
qnsqy hash-verify -i report.pdf --hash <the hash you saved>
The answer is either ✓ MATCH: report.pdf verified successfully or ✗ MISMATCH: report.pdf hash does not match!, followed by the expected and computed values.
Troubleshooting Common Issues
"Permission denied"
You do not have write access to the place where QNSQY is trying to create the output file. Common fixes:
- Write to your home folder instead:
qnsqy encrypt -i /some/path/file.txt -o ~/encrypted_file.qs - On Linux, check the folder's permissions with
ls -la - On Windows, do not write into system-protected folders such as
C:\Program Files
On Linux, QNSQY also restricts which folders it can reach while it runs (Landlock). If a path is refused, use a folder inside your home directory.
"Output file already exists - use --force to overwrite"
QNSQY never replaces an existing file by surprise. Choose another output name with -o, move the old file away, or add -f if you really want to replace it.
"File too large"
On the command line, the Free plan has no file-size limit: its algorithm, ML-KEM-512, has no limit on any plan. On Pro, ML-KEM-768 has no limit either, and ML-KEM-1024 is limited to 25 GB per file. Business has no limit. The desktop app in the current release is stricter: it stops at 100 MB per file on Free and 25 GB on Pro, whatever the algorithm, so use the command line for larger files.
"Wrong password or corrupted file"
QNSQY cannot recover your password. This is deliberate: a password-recovery backdoor would work for attackers too. If the password is lost, the data in a password-only file is lost with it.
To avoid this:
- Keep your encryption passwords in a password manager
- Use a passphrase of four or five random words: easier to remember and still strong. NIST's current guidance (SP 800-63B-4) asks for at least 15 characters for a password used on its own
- For important files, encrypt to a key pair as well, or use Business threshold encryption, where any M of N chosen people can open a file together, so no single lost secret locks you out
"This file was created with a higher-tier version of QNSQY"
The file was made on a higher plan than the one you are on now. In the current release, each file records the plan of the account that made it, and QNSQY opens the file only on that plan or a higher one. A file made while signed in to Pro opens on Pro or Business; a file made on Business opens only on Business; a file made on Free, or while signed out, opens on every plan. Sign in to an account on that plan (or, if your paid plan is offline-expired, reconnect so it can check in), then decrypt again.
"Command not found: qnsqy"
Your terminal cannot find the qnsqy program. Usually:
- On Linux, the packages install it as
/usr/bin/qnsqy; open a new terminal window after installing and try again - On Windows, close and reopen Command Prompt or PowerShell after running the installer, so it picks up the new PATH
Encryption Seems Slow
QNSQY deliberately uses a memory-hard password function (Argon2id) that takes 128 MB of memory by default, so each password operation takes a noticeable moment: about a second for a small file on our published test machine. The same cost applies to anyone guessing your password. With a long random passphrase that makes guessing impractical; no setting can make a short or common password strong.
For large files, the password cost is paid once per file and the rest is fast AES-256-GCM encryption. Measured speeds are on our validation page.
What to Learn Next
Now that you can encrypt, decrypt, sign, verify and shred files, here are the next topics to explore:
- The user guide and the command reference for every command and option
- Why hybrid encryption helps against quantum computers
- How Argon2id makes passwords much harder to crack
- Batch encryption for encrypting many files at once (Pro and Business)
Sources
- NIST FIPS 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard (ML-KEM) - https://csrc.nist.gov/pubs/fips/203/final
- NIST FIPS 204: Module-Lattice-Based Digital Signature Standard (ML-DSA) - https://csrc.nist.gov/pubs/fips/204/final
- NIST SP 800-63B-4: Digital Identity Guidelines, Authentication and Authenticator Management - https://pages.nist.gov/800-63-4/sp800-63b.html
- RFC 9106: Argon2 Memory-Hard Function for Password Hashing and Proof-of-Work Applications - https://www.rfc-editor.org/rfc/rfc9106
- NIST SP 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) - https://csrc.nist.gov/pubs/sp/800/38/d/final
Related Articles
Originally published at quantumsequrity.com/blog/getting-started-cli.