Skip to content

Home

Jump to bottom
DK edited this page Feb 4, 2025 · 11 revisions

replicat

Cryptography

Replicat supports both encrypted (the default) and unencrypted repositories.

Encrypted repositories

For encrypted repositories, Replicat will use symmetric encryption to encrypt chunks and snapshots. To enable encryption, you will need a key, which Replicat can generate for you, and an optional password.

Keys

A Replicat key is a JSON object that contains secrets for the cryptographic primitives that control how the data is split into chunks, visibility of chunks of data, and more. Because anyone with your key can decrypt your data, you need to store it securely or protect it with a password. If you provide a password when initialising a repository or adding a new key, Replicat will encrypt the key using your password. In such cases, both the key and the password are required to unlock and use the repository.

You can create multiple keys with different passwords and share those with other people.

If you ask Replicat to create a shared key, it will copy some of the secrets from your key to the new key, so that you and the owner of the new key could use deduplication features together, meaning data uploaded by you could be reused (referenced and decrypted) by the other person. That other person will also be able to create new shared keys by copying secrets that were originally copied to their key from your key, and so on. Think of it as a web of trust of sorts. If this behaviour is undesirable, you can create independent keys (the default).

Snapshots

Names of files, file timestamps, and all other file metadata within snapshots is encrypted, and it can only be decrypted by the snapshot creator. Hash digests of chunks referenced by the snapshot are encrypted and can be decrypted by all owners of shared keys for the purposes of deduplication. In other words, owners of shared keys may be able to confirm that a specific piece of data exists within your snapshots.

Snapshot name is simply the hash digest of the encrypted snapshot file.

Chunks

When creating a snapshot, the input data is divided into chunks using a content-defined chunking (CDC) algorithm that incorporates a secret for randomisation. To reduce the risk of successful confirmation-of-file attacks, chunks are encrypted using a combination of their content's hash digest and a separate secret. The chunk name is derived from its hash digest and the third secret.

Owners of shared keys can encrypt and decrypt chunks and verify whether a specific chunk of data exists in the repository. This is possible because the secrets used for CDC, encryption/decryption, and name generation are shared.

Unencrypted repositories

In unencrypted repositories, chunks, snapshots, and all other data are stored in plaintext. The storage names for chunks and snapshots are simply the hash digests of their contents.

Settings

By default, Replicat uses the following cryptographic primitives and settings:

  • AES256-GCM for encryption
  • Scrypt (only for password-protected keys) with n = 2 ^ 20, r = 8, p = 1 as the slow KDF
  • BLAKE2b for hashing, fast KDF, and HMAC
  • GCLMULChunker for CDC, producing chunks between 128K and 5.12M in size with default parameters

Encryption, hash, and chunking algorithms, as well as their parameters, are configured at the repository level and apply to all users of the repository, while MAC and KDFs are configured per-key.

Replicat's default parameters and selection of cryptographic primitives should work well for most users but they do allow for some customisation if you know what you are doing.

Supported primitives and their parameters:

Name Use Parameters (with defaults) Description Notes
aes_gcm AEAD key_bits (256 [bits]), nonce_bits (96 [bits]) AES in GCM mode Supports 128, 192, and 256 bit keys
chacha20_poly1305 AEAD ChaCha20‑Poly1305
scrypt Key derivation n (2 ^ 20), r (8), p (1) Scrypt KDF Preferred for low-entropy inputs
blake2b Hash, HMAC, key derivation length (64 [bytes]) BLAKE2b BLAKE2b-based "KDF" should only be used for high-entropy inputs
sha2 Hash bits (512 [bits]) SHA2 Supported digest sizes are 224, 256, 384, and 512 bits
sha3 Hash bits (512 [bits]) SHA3 Supported digest sizes are 224, 256, 384, and 512 bits
gclmulchunker CDC min_length (128K [bytes]), max_length (5.12M [bytes]) Content-defined chunking algorithm based on carry-less multiplication (CLMUL)

The supported settings hierarchy is

├── hashing
│   ├── name: <hashing adapter name>
│   └── ... 
├── chunking
│   ├── name: <chunking adapter name>
│   └── ...
└── encryption
    ├── cipher
    │   ├── name: <cipher adapter name>
    │   └── ...
    ├── kdf
    │   ├── name: <slow kdf adapter name>
    │   └── ...
    ├── shared_kdf
    │   ├── name: <fast kdf adapter name>
    │   └── ...
    └── mac
        ├── name: <mac adapter name>
        └── ...

where ... denotes parameters for the selected adapter. Using the table above, the default Replicat settings are

├── hashing
│   ├── name: blake2b
│   └── length: 64
├── chunking
│   ├── name: gclmulchunker
│   ├── min_length: 128000
│   └── max_length: 5120000
└── encryption
    ├── cipher
    │   ├── name: aes_gcm
    │   ├── key_bits: 256
    │   └── nonce_bits: 96
    ├── kdf
    │   ├── name: scrypt
    │   ├── n: 1048576
    │   ├── r: 8
    │   ├── p: 1
    │   └── length: 32
    ├── shared_kdf
    │   ├── name: blake2b
    │   └── length: 32
    └── mac
        ├── name: blake2b
        └── length: 64

When using Replicat CLI, you can override these settings for commands that support them.

Clone this wiki locally