Encryption

Summary

Where the app uses cryptography

Backup and credential files (SSKB2)

Settings → Backup & Restore and Credentials → Send credentials both write this format. A backup's file name ends in .sskb, a credential file's in .sskc. The file holds one JSON document, encrypted with a key derived from a passphrase you choose. The passphrase must be at least 8 characters, and the app never stores it.

All numbers are unsigned and big-endian. The offsets are those of a file the app writes today, with a 16-byte salt.

• Key: Argon2id (RFC 9106, version 0x13) with the memory, passes and lanes in the header (64 MiB, 3 and 4 today, RFC 9106's second recommended setting), the header's salt, and a 32-byte output. The password is the UTF-8 encoding of your passphrase after Unicode NFC normalization, so the same passphrase typed on different keyboards gives the same key. There is no secret value or associated data. This is the same derivation sync uses for its keyring.
• Cipher: AES-256-GCM (NIST SP 800-38D) with a 12-byte nonce and a 16-byte tag. The associated data is the whole header, every byte before the ciphertext (49 bytes today), so no header byte can be changed without the tag failing.
• What's inside: UTF-8 JSON. A backup is an object with "kind": "full_backup", "version": 1, the time it was made (exportedAt), and your credentials, groups, hosts, portForwards, snippets and alertDestinations. A credential file has "kind": "credentials", "version": 1, exportedAt and only the credentials you picked, each with its name, username, type, password, private key, key passphrase and privilege setting.
• Limits when opening a file: the app opens a file only if its settings are within these bounds: memory at most 256 MiB and at least 8 KiB per lane, 1 to 16 passes, 1 to 16 lanes, and a salt of 16 to 64 bytes. A file with an unknown key derivation or cipher ID, or with settings above those bounds, is reported as made by a newer version and not opened. So the settings can be raised later without a new format.

A wrong passphrase and a damaged or altered file both fail the authentication tag, and the app can't tell them apart. Nothing is restored from a file that fails.

Versions of the app from before SSKB2 can't open SSKB2 files. They report that the file doesn't look like a backup, and change nothing.

Older backup files (SSKB1)

The app still opens SSKB1 files, and always will, but no longer writes them. Earlier versions wrote backups and credential files in this format. The JSON inside is the same as above.

• Key: PBKDF2 with HMAC-SHA256 (RFC 8018), 210,000 iterations, a 32-byte output. Its inputs are the salt and the UTF-8 bytes of the passphrase exactly as typed, without normalization, as those files were made.
• Cipher: AES-256-GCM, with no associated data. Note that the tag comes before the ciphertext in this format.

Sync

Sync keeps your hosts and related records the same on your devices, through a WebDAV server you choose. (The privacy policy lists what syncs.) The server only ever receives encrypted files, plus one unencrypted file that holds nothing secret. The sync folder looks like this:

server-sidekick-sync/
  keyring.json              the data key, encrypted with your passphrase
  devices/<deviceId>.ssks   one encrypted file per device

Setting up sync creates a random 256-bit data key and a random 128-bit key ID for it. Every device file is encrypted under a key derived from the data key. Each device keeps the data key in its secure storage, and it is stored on the server only after being encrypted with a key derived from your sync passphrase. The sync passphrase must be at least 15 characters, counted as Unicode code points after NFC normalization. It never leaves your devices and is not stored.

The keyring (keyring.json)

A JSON object. Byte strings are standard Base64 with padding.

{
  "format": 1,
  "keyId": "<16 bytes>",
  "kdf": {"alg": "argon2id", "m": 65536, "t": 3, "p": 4, "salt": "<16 bytes>"},
  "wrappedKey": "<nonce (12) | ciphertext (32) | tag (16)>"
}

• Key-encryption key: Argon2id (RFC 9106, version 0x13). The defaults are 64 MiB of memory (m, in KiB), 3 passes (t) and 4 lanes (p), RFC 9106's second recommended setting. It uses the 16-byte salt and makes a 32-byte output, with no secret value or associated data. The password is the UTF-8 encoding of your passphrase after Unicode NFC normalization. The settings are stored in the file, so they can be raised later without changing the format. A device uses a keyring only if its settings are within these bounds: memory at most 1 GiB and at least 8 KiB per lane, 1 to 16 passes, and 1 to 16 lanes.
• wrappedKey: the data key, encrypted with AES-256-GCM under the key-encryption key and a random 12-byte nonce. The associated data is the ASCII text ssk-sync-keyring-v1 followed by the 16 bytes of the key ID.
• While a key is being replaced (Settings → Sync → Rotate key), the keyring briefly also has "previous": {"keyId", "wrappedKey"}. That is the old data key, wrapped under the same key-encryption key with the associated data ssk-sync-keyring-previous-v1 | the old key ID. Every file on the server stays readable until each device has re-encrypted its own.
• After a key has been replaced, the keyring can have "replaced": {"keyIds": [...], "mac": "<32 bytes>"}. That is up to 8 earlier key IDs, newest first. Your other devices use it to recognise the new key as a replacement and carry on without setting up again. mac is HMAC-SHA256 over ssk-sync-keyring-replaced-v1 | key ID | each listed key ID in order. Its key is HKDF-SHA256 (RFC 5869) of the data key, with no salt (RFC 5869's default), the info string ssk-sync-keyring-replaced-v1 and 32 bytes of output. Only a device that unlocked the data key with your passphrase can check or write that list.

Device files (SSKS1)

Each device writes only its own file, devices/<deviceId>.ssks. The app makes each device ID a random UUID (version 4); a reader accepts any ID of 1 to 64 characters from A–Z a–z 0–9 _ -.

• File key: HKDF-SHA256 (RFC 5869) of the data key, with the file salt, the info string ssk-sync-device-file-v1 and 32 bytes of output. Every write therefore has its own key.
• Cipher: AES-256-GCM. The associated data is SSKS1 | key ID | the UTF-8 device ID taken from the file's name. A file copied or renamed to another device's name fails to decrypt, and so does one encrypted under another key.
• Plaintext and padding: the payload's length as a 4-byte big-endian number, then the payload, then zero bytes. The zero bytes make the whole file a power of two in size, at least 4 KiB, so its size reveals only roughly how much you sync. The file's 81 bytes of header and tag are counted in that size. Files over 64 MiB are neither written nor read, and a reader rejects padding that isn't all zeros.
• Payload: a UTF-8 JSON object with the format version ("format": [1, 1]), the device ID (device), a write counter (seq), the writer's clock in milliseconds (clock) and the synced records (records). It can also have the device's display name (name): the device model, or a name you gave it in Settings → Sync, never your device's own name. Because the name sits inside the encrypted payload, the server never sees it.

A torn or tampered file fails its authentication tag. It is skipped, never partly applied. A file whose write counter is lower than one already seen from that device is ignored as a rollback.

Adding a device with a code (SSKI1)

A device that already syncs can show a QR code (Settings → Sync → Add a device) that lets a new device join without typing the sync passphrase. The code holds a one-time secret; the data key goes to the server encrypted under a key derived from that secret, so neither the code nor the server's copy opens anything on its own.

The code is this text, as a QR code or copied, with each value URL-encoded:

server-sidekick-sync:join?v=1&url=<sync folder address>&user=<username>&cert=<certificate fingerprint>&id=<invitation ID>&secret=<secret>

• id is 16 random bytes and secret is 32 random bytes, each written in URL-safe Base64 without padding (22 and 43 characters).
• cert is present only if the inviting device trusts the server's certificate by its fingerprint: the certificate's SHA-256 as 64 hex digits.
• The code never holds the sync passphrase, the server's password or the data key.

The invitation file is invites/<id>.sski in the sync folder:

• Key: HKDF-SHA256 (RFC 5869) of the code's 32-byte secret, with the invitation ID's 22 characters (as ASCII text, not the decoded bytes) as the salt, the info string ssk-sync-invite-v1 and 32 bytes of output.
• Cipher: AES-256-GCM. The associated data is SSKI1 | the invitation ID's 22 characters, so a file renamed to another ID fails to decrypt.
• Plaintext: UTF-8 JSON: {"v": 1, "keyId": "<16 bytes>", "key": "<32 bytes>", "expires": <milliseconds since 1970>}, with the data key and its ID in standard Base64.
• Lifetime: an invitation expires 10 minutes after it is made, by the inviting device's clock; the new device allows up to 5 minutes more for clocks that disagree. The new device deletes the file before it uses the key, and the inviting device deletes it when its dialog closes or once it has expired.

Standards and libraries

The app uses only these algorithms, each as its standard defines it. All of them run in code built into the app.

Every random key, salt, nonce and ID in the files described on this page comes from the operating system's secure random number generator, through Dart's Random.secure().

Notation

• | means the byte strings are joined end to end.
• Text written in code inside a key derivation or associated data means its ASCII bytes, with no terminator or length prefix.
• Lengths are in bytes unless they say otherwise. KiB is 1,024 bytes and MiB is 1,048,576 bytes.

Questions about this page, or a security problem to report: see Support.