# Kopya encryption format

Format version 1 (account key derivation `argon2id-v1`). Last updated 30 October 2026.
Published at https://kopya.uk/security#spec. Test vectors: https://kopya.uk/security/crypto-vectors.json

This document describes, byte for byte, how Kopya clients encrypt files, names, notes,
thumbnails and keys before anything is uploaded, and what the server receives. It is
written so that anyone can check our claims and so that other software can read and
write the same data. Every format below has a worked example in `crypto-vectors.json`.

Kopya has not been independently audited yet. If you find a mistake in this document or
a weakness in the design, please write to support@kopya.uk.


## 0. Notation

* `||` joins byte strings.
* `b64` is standard base64 with padding. It is used for every value the server stores.
* `b64url` is URL-safe base64 without padding. It is used only in share-link fragments.
* `utf8(x)` is the UTF-8 encoding of the text `x`.
* All symmetric encryption is **AES-256-GCM** with a **96-bit (12-byte) random IV** and a
  **128-bit (16-byte) tag**, the 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.getRandomValues` in 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'))` (Unicode NFKC normalisation first) |
| 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. Accounts created this way 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` (key-encryption key) 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:

1. The client asks the server for the account's key-derivation settings: the method
   (`argon2id-v1` or `pbkdf2-sha256`), the salt and, for PBKDF2, the iteration count.
2. The client derives `secret`, then `auth_key` and `KEK`.
3. The client sends only `b64(auth_key)`. The server compares it with a password hash
   of `auth_key` (PHP `password_hash`) and, if it matches, returns a session token and
   `wrapped_master`.
4. The client opens `wrapped_master` with `KEK`. `KEK`, the master key and the password
   never leave the device.

With two-factor sign-in switched 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

Each item (file, folder or note) is a node. Per node:

**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 of a file 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 date
  taken read from the photo's EXIF data (`0` means the photo was checked and has no date;
  absent means it was not checked yet).
* folder: `{"name": "..."}`
* note: `{"name": "<title>"}`, with the note text stored separately as
  `content = 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` is the total number of chunks (4 + 4 bytes,
big-endian). The AAD is not stored anywhere; the reader rebuilds it from the position it is
reading and the chunk count. Because the position and the 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_size` above
  64 MiB and any chunk larger than `chunk_size + 28` bytes.


## 7. Changes

* 2026-10-30: first public version of this document.
