Kopya encryption format · version 1 · 30 October 2026
How Kopya clients encrypt files, names, notes, thumbnails and keys before anything is uploaded, and what the server receives. Every format has a worked example in crypto-vectors.json. Kopya has not been independently audited yet; if you find a mistake here or a weakness in the design, please write to support@kopya.uk.
0. Notation
‖joins byte strings (||in the text file).b64is standard base64 with padding, used for every value the server stores.b64urlis URL-safe base64 without padding, used only in share-link fragments.utf8(x)is the UTF-8 encoding of the textx.- All symmetric encryption is AES-256-GCM with a 12-byte random IV and a 16-byte tag appended to the ciphertext. An IV is never reused with the same key.
- Random values come from the platform’s cryptographic random generator (
crypto.getRandomValuesin browsers).
1. Sealed blob
Every wrapped key, every piece of metadata and every note uses the same layout:
sealed = iv[12] ‖ ciphertext ‖ tag[16]
seal(key, plaintext, aad) encrypts with a fresh random IV and returns sealed. There is no additional authenticated data (AAD) unless a section says otherwise. A sealed value is 28 bytes longer than its plaintext.
2. Account keys
| Step | Definition |
|---|---|
| Password | utf8(password.normalize('NFKC')) |
Key derivation (current, argon2id-v1) | Argon2id (version 0x13), memory 65536 KiB (64 MiB), 3 iterations, parallelism 1, 16-byte random salt per account, 32-byte output, called secret |
Key derivation (older accounts, pbkdf2-sha256) | PBKDF2-HMAC-SHA256, 600 000 iterations, 32-byte output. These accounts are moved to Argon2id at their next sign-in |
| Split | HKDF-SHA256(secret, salt = empty, info, length 32). auth_key uses info upload/auth/v1; KEK uses info upload/kek/v1 |
| Master key | 32 random bytes, made on the device when the account is created |
| Wrapped master key | wrapped_master = b64(seal(KEK, master_key)) |
| Recovery key | 32 random bytes, shown once as 8 groups of 8 lowercase hex characters joined with - |
| Recovery copy | wrapped_master_recovery = b64(seal(recovery_key, master_key)) |
The upload/ prefix in the HKDF labels is historical (the project’s working name). It is part of the format and does not change.
Signing in:
- The client asks the server for the account’s key-derivation settings: the method, the salt and, for PBKDF2, the iteration count.
- The client derives
secret, thenauth_keyandKEK. - The client sends only
b64(auth_key). The server compares it with a password hash ofauth_key(PHPpassword_hash) and, if it matches, returns a session token andwrapped_master. - The client opens
wrapped_masterwithKEK.KEK, the master key and the password never leave the device.
With two-factor sign-in on, the server first answers that a code is required; the client repeats step 3 with a 6-digit TOTP code (RFC 6238, 30-second steps) or a one-time backup code.
The server stores the salt and method, password_hash(auth_key), wrapped_master and wrapped_master_recovery. It cannot open either wrapped copy. If the password and the recovery key are both lost, the master key cannot be recovered by anyone, and neither can anything encrypted under it. Changing the password re-wraps the same master key under a new KEK; files are not re-encrypted. Recovering with the recovery key does the same.
3. Files, folders and notes
File key. Each file has its own random 32-byte key: wrapped_key = b64(seal(master_key, file_key)). The file key never changes for the life of the file, so older versions stay readable with it.
Metadata. meta = b64(seal(master_key, utf8(JSON))), for files, folders and notes:
- file:
{"name": "...", "mime": "...", "size": <plaintext bytes>, "mtime": <ms since epoch>}and, for photos (jpg, jpeg, png, webp), optionally"taken": <ms since epoch>, the EXIF date taken (0= checked, no date; absent = not checked yet). - folder:
{"name": "..."} - note:
{"name": "<title>"}, with the text stored separately ascontent = b64(seal(master_key, utf8('{"t": "<text>"}'))).
Clients keep fields they do not recognise when they rewrite metadata.
Content. The plaintext is split into chunks of chunk_size bytes. The web client uses 8 MiB (8 388 608 bytes) chunks, and 16 MiB chunks for files larger than 1 GiB; the last chunk is shorter, and an empty file has no chunks. Readers must always use the chunk_size stored with the file. Each chunk is stored as its own object:
chunk_i = iv[12] ‖ AES-256-GCM(file_key, iv, plaintext_i, aad = u32be(i) ‖ u32be(n)) ‖ tag[16]
where i is the zero-based chunk index and n the total number of chunks (4 + 4 bytes, big-endian). The AAD is not stored; the reader rebuilds it from the position it is reading and the chunk count. Because position and count are part of every tag:
- a chunk moved to another position fails its tag check;
- a chunk from another file fails (different key);
- cutting chunks off the end is noticed: if the server also lowers the chunk count it reports, every remaining chunk fails, because each was sealed with the real count; if it does not, the reader finds chunks missing. (The plaintext size is also inside the sealed metadata.)
The size the server records for a file is the sum of the encrypted chunk sizes (plaintext + 28 bytes per chunk), so it reveals the plaintext size to within that overhead.
Thumbnail. Images and videos get a small preview (WebP or JPEG, at most 400 px on the long side), made on the device and sealed with the file key and the ASCII AAD thumb:
thumb = iv[12] ‖ AES-256-GCM(file_key, iv, image_bytes, aad = "thumb") ‖ tag[16]
The different AAD means a thumbnail can never be passed off as a content chunk, or the other way round.
4. Shares
Share key. A share has its own random 32-byte key K. The link is
https://app.kopya.uk/s/<share_id>#k=<b64url(K)>
Browsers do not send the part after # to the server, so the server never receives K.
share.meta = b64(seal(K, utf8(JSON {name, mime, size})))- file shares:
wrapped_key = b64(seal(K, file_key)) wrapped_sharekey_owner = b64(seal(master_key, K)), so the owner can show the link again.
Password-protected shares. The link has no #k= part. Instead:
secret = PBKDF2-HMAC-SHA256(utf8(password.normalize('NFKC')), salt, 600000, 32)
verifier = HKDF-SHA256(secret, salt = empty, info "upload/share-verify/v1", 32)
wrapKey = HKDF-SHA256(secret, salt = empty, info "upload/share-wrap/v1", 32)
wrapped_sharekey_pw = b64(seal(wrapKey, K))
The visitor’s browser sends b64(verifier). The server stores only a hash of the verifier and returns wrapped_sharekey_pw when it matches; the browser opens it with wrapKey. Attempts are rate limited.
Folder shares are snapshots. The owner’s browser seals each item for the share: {node_id, meta: b64(seal(K, ...)), wrapped_key: b64(seal(K, file_key))}. Files added to the folder later are not visible through the link until the owner updates the share.
5. What the server stores
Per account: email address, key-derivation method and salt, password_hash(auth_key), wrapped_master, wrapped_master_recovery, plan and settings, sign-in sessions (a hash of each random session token), and, if two-factor sign-in is on, the TOTP secret (encrypted at rest with a server key, because the server has to check the codes).
Per node: an id, the parent folder’s id, the type (file, folder or note), meta, content (notes), wrapped_key, the encrypted size, chunk_size, chunk count, whether a thumbnail exists, and created, changed and deleted timestamps.
Content chunks and thumbnails are stored as separate objects in EU object storage, under u<user_id>/<blob_id>/<chunk_index | thumb>. Browsers upload and download them directly with short-lived signed addresses. When an upload finishes, the server checks that every chunk is present with the expected size before the file is listed.
The server allows duplicate names in one folder and names that some operating systems cannot use, because it cannot read names; they only mean something after decryption.
6. Rules for any implementation
- Never log, store or send in plaintext the password,
secret,auth_key(other than sending it at sign-in),KEK, the master key, file keys, share keys or the recovery key. - Never reuse an IV with the same key; use a fresh random IV for every seal.
- Always check the GCM tag, and treat a failed check as an error, never as data.
- Build the chunk AAD yourself from the position being read and the file’s chunk count, and never use a chunk whose tag check fails for that position.
- Do not trust server-provided sizes for memory allocation: reject a
chunk_sizeabove 64 MiB and any chunk larger thanchunk_size + 28bytes.
7. Changes
- 2026-10-30: first public version of this document.