QNSQY File Format Specification

1. Overview

QNSQY is a post-quantum encrypted container format developed by Quantum Sequrity for healthcare, defense, and other regulated organizations migrating from classical to post-quantum cryptography. The format encapsulates AEAD-encrypted data sealed by NIST-standardized post-quantum algorithms, with optional digital signatures, multi-recipient access control, threshold key sharing, and a tamper-evident audit chain.

This document describes version 6 of the format, current minor version 6.1. The format identifies itself by the four ASCII bytes QNS6 at file offset 0. Implementations at minor version 6.1 conceal the producing tier and most feature flags inside the AEAD-protected encrypted header (see section 12). Files written by 6.0 producers continue to decrypt unchanged; readers select the parsing path on the minor version field at offset 6.

2. File identification

3. Fixed header layout (bytes 0–127)

Readers MUST validate the magic at offset 0, the major version at offset 4, and reject any file whose major version differs from the supported value (currently 6). For v6.1 readers, byte 8 MUST be zero, and bytes 14–15 MUST contain only the public flag bits (mask 0x0046); a non-zero value in those reserved positions MUST cause the file to be rejected.

4. Algorithm identifiers

QNSQY uses NIST-standardized post-quantum primitives by default. The complete enumeration of allowed identifiers is specified by the reference implementation; the table below lists the principal values.

Signatures (when present) use ML-DSA-44/65/87 (NIST FIPS 204), SLH-DSA (NIST FIPS 205), or LMS / HSS (RFC 8554, NIST SP 800-208), encoded in the optional QSIG trailer block (section 7).

Hash profile. The KDF identifier (offset 11) and the hash identifier (offset 12) form a pair, and exactly two pairs are valid: (0x50, 0x60), the default profile, and (0x51, 0x61), the SHA-512 profile, which a writer can choose per file (reference implementation since September 2026). In the SHA-512 profile, HKDF-SHA-512 derives the file keys, the nonces and the key wraps; HMAC-SHA-512 truncated to 32 bytes computes the header MAC, the key commitment and the 24-byte integrity digest; and SHA-512 truncated to 32 bytes builds the Merkle tree and the file-name hash. Readers MUST reject any other pair, mixed or unknown, before deriving any key. Files in the SHA-512 profile carry their signature in a QSG2 trailer (section 7) instead of QSIG; LMS signatures keep a QSIG trailer in both profiles, and the trailer magic always names the digest, so a verifier never has to guess it.

Readers MUST reject any KEM, AEAD, KDF, hash or compression identifier they do not recognize, so that a file using an algorithm a reader does not implement fails to open instead of being misread.

5. Feature flags

The flag word at offsets 14–15 carries two disjoint sets of bits. The public mask (0x0046) drives parser layout decisions and stays in plaintext in v6.1. The private mask (0x01B9) controls cryptographic and feature behavior that the reader only needs after AEAD decryption; in v6.1, those bits live inside the encrypted-header meta prefix and the corresponding plaintext bits MUST be zero.

v6.1 readers MUST reject files where any private-mask bit is set in the plaintext flag word. Public-mask bits can be tested before the encrypted header is decrypted. Private-mask bits are only available after the encrypted-header meta has been authenticated by AEAD verification.

5a. Encrypted header meta (v6.1, 4-byte prefix)

v6.1 prepends a four-byte structure to the encrypted-header plaintext:

The remainder of the encrypted-header plaintext follows the same structure as in v6.0 (Argon2 parameters, confirmation block, wrapped DEK, KEM material, Merkle tree information, etc.). Encryption of the entire concatenated plaintext (meta + contents) is performed with the AEAD algorithm declared in the fixed header.

6. File body

Header size floor. A minor-version 6.1 writer reserves a fixed 32768-byte region for the encrypted header and zero-fills whatever the real header does not use, so the encrypted-header length at byte 80 (the true, unpadded length) is at most 32768. The MAC and QSDT marker follow at fixed offsets immediately after the 32768-byte region. Consequently every QNSQY file has a minimum size of 128 + 32768 + 32 + 4 = 32932 bytes, plus a 16-byte AEAD tag per chunk, plus the payload, plus (in recipient or hybrid mode) a plaintext KEM ciphertext block. The 65536-byte limit stated in sections 2, 3 and 8 is the READER's maximum accepted declared length, a denial-of-service bound and forward-compatibility margin, not the writer's reservation. The fixed region exists for four reasons: a DoS bound on header parsing, capacity for the worst-case header (HQC-256 hybrid, about 22 KB), a single-pass streaming write in which header contents such as the Merkle root are known only after the data chunks are written, and in-place rekey that rewrites the header into the same reservation. The fixed region is NOT a size-privacy mechanism: the true header length is present in plaintext at byte 80, and the exact size of the original data is present in plaintext at byte 88 (section 8.5).

7. Optional trailers

A QNSQY file MAY be followed by one or more append-only trailer blocks. Each trailer begins with its own four-byte ASCII magic.

QSIG signs a BLAKE3 digest, and QSG2 a SHA-512 digest, of every byte of the file before the trailer. A reader accepts a trailer only when its declared lengths end exactly at the end of the file or at the start of the next trailer, so trailer-like bytes inside the ciphertext are never mistaken for a trailer. Trailers are written after the integrity digest is taken and are not covered by the header MAC or the chunk authentication tags (section 8.4).

8. Security considerations

QNSQY files are encrypted with NIST-standardized post-quantum cryptography. The format does not execute code. Implementations MUST validate the QNS6 magic and the major version field before parsing any further content. Implementations MUST reject files whose declared encrypted header length exceeds 65536 bytes. The fixed header includes an Argon2id salt and a key commitment field which together prevent password-based decryption oracle attacks. The 32-byte BLAKE3 keyed-hash MAC over the headers prevents tampering. The AEAD construction over data chunks provides per-chunk authenticity. Improper key management MAY lead to permanent data loss; apart from the optional escrow trailer (QSEC, section 7), the format does not provide key recovery and recommends external mechanisms (threshold sharing) for that purpose.

The format provides its own confidentiality and integrity protection and does not depend on the transport for them. The subsections below give the full analysis; the IANA media type registration summarizes them.

8.1 Active content. The format contains no active content: no executable code, scripts, macros, or references that cause code to be loaded or run, or data to be fetched or sent over a network, when a file is parsed or decrypted, and decryption does not execute anything contained in the file. The decrypted payload is arbitrary data chosen by the sender and can itself be a program; how it is handled is the responsibility of the application that consumes it. A payload marked as a directory archive (flag 0x0010, sealed inside the encrypted header in v6.1) is a tar archive that the reference implementation unpacks after decryption. An implementation that unpacks it MUST keep every output path inside the destination directory. The reference implementation skips entries whose path is absolute or contains .., writes only regular files and directories (link, device and FIFO entries are skipped), does not apply stored permissions or extended attributes, and stops at 1 GiB per extracted file. The reference implementation can also produce self-extracting polyglot files (an image carrier with a shell launcher, marker QSP4). Those contain a launcher script, are not files of this media type, and need to be labelled with a different one.

8.2 Confidentiality. The data is split into chunks. Each chunk is encrypted with the AEAD named at offset 10, AES-256-GCM (NIST SP 800-38D) or XChaCha20-Poly1305 (draft-irtf-cfrg-xchacha), under a per-file data key, with its own derived nonce and authentication tag. The data key is protected by one or more of: a password, through Argon2id (RFC 9106); a recipient public key, through ML-KEM (NIST FIPS 203) or HQC, alone or combined with X25519 (RFC 7748); a password and a private key together (hybrid mode, flag 0x0004); or a key file (flag 0x0080). Without the secret that protects the data key (password, private key or key file), the chunk data stays confidential under the standard security definitions of the chosen AEAD. A password-protected file is only as strong as its password: anyone who has the file can try passwords offline, and the Argon2id parameters slow down guessing but cannot make a weak password safe.

8.3 Integrity. Three mechanisms protect the file: (1) the 32-byte header MAC over the fixed header, the multi-recipient slots block when present, and the encrypted header, which binds the algorithm identifiers, the key-derivation parameters, the salt and the flag bits; (2) the AEAD authentication tag of every chunk; and (3) a Merkle tree over the chunk ciphertexts and tags, whose root is stored inside the encrypted header and is checked before any plaintext is written, which detects reordered, substituted, dropped and truncated chunks. The optional 24-byte integrity digest in the reserved bytes of the fixed header (section 3) uses no secret key. It detects accidental corruption without the password, but anyone who modifies a file can recompute it, so it is not protection against deliberate tampering.

8.4 Origin authentication. Encryption does not authenticate the sender: anyone who knows the password, or holds a recipient's public key, can create a valid file. Origin authentication comes only from a signature trailer (section 7), made with ML-DSA (NIST FIPS 204), SLH-DSA (NIST FIPS 205) or FN-DSA (Falcon; FIPS 206 not yet published), each also available combined with Ed25519 (RFC 8032), or with LMS / HSS (RFC 8554, NIST SP 800-208). A combined signature is valid only if both of its signatures verify. The trailer carries the signer's public key, so a valid signature proves only that the file matches that key; a verifier MUST compare the key with one it already trusts before treating the file as coming from the key's holder. Because trailers are not covered by the header MAC or the chunk tags, a signature trailer can be removed, or replaced by one made under another key, without affecting decryption. Recipients SHOULD treat a file without a valid signature from a trusted key as having no authenticated origin.

8.5 Metadata visible without a key. The fixed header is authenticated by the header MAC (8.3) but not encrypted, and MUST NOT be treated as confidential. Before any key is available, an observer can read: the magic and the version; the KEM, AEAD, KDF, hash and compression identifiers (offsets 9 to 13); the public flag bits (recipient, hybrid and multi-recipient mode); the salt; the key commitment; the encrypted-header length; the exact size of the original data (offset 88); the password-hashing parameters; and, when present, the integrity digest and its indicator byte. In recipient and multi-recipient mode the KEM ciphertexts are stored in plaintext, so the number of recipients is visible, although the slots carry no recipient identifiers. When compression is used, the size of the chunk data compared with the original size shows how compressible the data is. Version 6.1 seals the producing tier and the private flag bits inside the encrypted header (section 11), with two intentional exceptions: the integrity indicator at reserved[24], and the QSEC magic of an appended escrow trailer, which shows that escrow is in use. Operators who need to hide the use of escrow MUST NOT use the escrow feature.

8.6 Resource exhaustion. The fixed header is parsed before any key is available, so readers MUST check every declared length, count and cost against fixed bounds before using it to allocate memory or to run a key derivation. The reference implementation accepts: an encrypted-header length of 48 to 65536 bytes; a chunk size of 16 KiB to 64 MiB; at most 1,000,000 chunks; at most 10,000 Merkle intermediate nodes; and Argon2id memory of 128 to 512 MiB, 3 to 20 iterations and parallelism 1 to 16 (section 3). Compression (identifier 0x70, Zstandard) is applied to each chunk before encryption. Readers MUST bound the decompressed size of each chunk; the reference implementation allows only a small margin over the expected chunk size and never more than 64 MiB per chunk. Directory archives are bounded as described in 8.1.

8.7 Post-quantum security. Against a quantum adversary, confidentiality in recipient and hybrid modes rests on the post-quantum KEM (ML-KEM or HQC). The combined KEM modes derive the key from both the post-quantum KEM and X25519, so confidentiality holds as long as either component is unbroken. The 256-bit keys of AES-256-GCM and XChaCha20-Poly1305 keep a large margin against Grover-type search. The security of a file reduces to that of the algorithms named in its header and to the secrecy of the password or private key. The reference implementation uses NIST-standardized algorithms but is not FIPS 140-validated, and no CMVP certificate is claimed.

8.8 Implementation notes. The reference implementation uses the RustCrypto ml-kem, ml-dsa and slh-dsa crates, the dalek crates for X25519 and Ed25519, and the RustCrypto AES-GCM implementation, which uses the processor's AES instructions where available and a constant-time software implementation otherwise. MAC and key-commitment comparisons use constant-time equality. Argon2id makes data-independent memory accesses only in the first half of its first pass (RFC 9106); later accesses depend on the password, which matters only to an attacker who can observe the memory-access pattern of the device doing the derivation. The format makes no claim of resistance to physical side channels (power, electromagnetic emanation, fault injection).

9. Interoperability considerations

QNSQY is defined and maintained by Quantum Sequrity. Implementations should reject unknown major version bytes. Minor version increments preserve backward compatibility. A FIPS-mode build of the reference implementation, in development and not yet released, is designed to restrict algorithm identifiers to NIST-approved values (ML-KEM, ML-DSA, SLH-DSA, LMS, AES-256-GCM, SHA-2 / SHA-3, HKDF, PBKDF2). The reference implementation is not FIPS 140-validated.

Versions. All multi-byte integers in the fixed header are little-endian. The major version (offset 4) changes only for incompatible format changes; readers MUST reject a file whose major version they do not support. Readers that implement version 6.1 MUST also read version 6.0 files, selecting the layout by the minor version at offset 6 (section 11).

Algorithms. Readers MUST reject algorithm identifiers they do not recognize and KDF and hash pairs other than the two defined in section 4, so that a file using an algorithm a reader does not implement fails to open instead of being misread.

Media type parameters and transport. The optional version parameter of application/vnd.quantumsequrity.qnsqy carries the format version as ASCII decimal MAJOR.MINOR (for example version=6.1). It is advisory: the version recorded in the file is authoritative. No charset parameter is defined, because the content is binary; a charset parameter, if present (some tools add charset=binary), has no meaning for this type and MUST be ignored. The content can contain any octet values, so transports that are not binary-clean, such as Internet mail, MUST carry it with a content transfer encoding such as base64 (RFC 2045). HTTP and direct file transfer need no special encoding.

10. Related specifications

• QSPG — Polyglot carrier variant
• QSDN — Deniable encryption variant

11. v6.1 privacy refactor (informational)

Version 6.1 is a non-breaking minor revision that hides the producing tier and the six private feature flag bits from observers who can see the file but cannot decrypt it. v6.0 producers continue to be readable: a v6.1 reader detects the on-disk minor version and follows the v6.0 backward-compatibility branch with the legacy plaintext layout for pre-existing files.

The wire-format change is limited to: (a) zeroing byte 8 (tier) on disk, (b) zeroing all private-mask bits in the flag word at offsets 14–15, (c) prepending a four-byte EncryptedHeaderMeta to the encrypted header plaintext that carries the authoritative tier and private flag bits, and (d) replacing the FLAG_INTEGRITY plaintext gate with a structural indicator at reserved[24] == 0x01 so the integrity hash remains verifiable without the decryption key. The header MAC scope and AEAD construction are unchanged; the moved fields are authenticated by the same MAC and AEAD tag that already protect the encrypted header.

The privacy claim is precise and excludes two residual signals that the format intentionally leaves plaintext-visible:

• Integrity-presence indicator at reserved[24] == 0x01. By design, so verify-integrity works without the decryption key. A passive observer learns whether the file carries an integrity hash, but cannot recover the hash value's relation to plaintext.
• Escrow trailer magic. When the optional escrow trailer is appended after the chunked body, the trailer's four-byte ASCII QSEC magic is plaintext-visible at end-of-file. Operators who need the existence of escrow itself to be hidden MUST NOT use the escrow feature.

The fixed header also continues to reveal the format magic, version, algorithm tags, Argon2id parameters, salt, key commitment, encrypted-header length, plaintext file size, and the public flag bits. These fields are required for the parser to start decrypting and are not part of the privacy claim.

12. IANA media type registration

A single IANA media type registration covers the .qs primary format: application/vnd.quantumsequrity.qnsqy. The registration (RFC 6838, vendor tree) was submitted to IANA through the form at iana.org/form/media-types on 11 September 2026, and IANA registered it on 28 October 2026. It is listed in the IANA media types registry. The security and interoperability fields of the registration summarize sections 8 and 9 of this document. The internal sub-formats .qsdn, .qspg, .qss2, .qsv, .qsig, .qsthresh, .qstl, .qsym, .qskf, and .qsabe remain QNSQY-internal tooling formats and are not being submitted as separately registered media types.

A PRONOM format signature (UK National Archives) and a magic(5) entry for upstream file(1) have also been prepared; both submissions are pending.

13. Reference implementation and contact

Reference implementation: a Rust implementation of the QNSQY format is available under commercial license. Evaluation builds and binary downloads: quantumsequrity.com/download. Source-license enquiries: [email protected].

Specification queries and IANA / PRONOM registration matters: [email protected].