> ## Documentation Index
> Fetch the complete documentation index at: https://docs.everabyte.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Encryption architecture

> How Everabyte encrypts files in two layers, what governs decryption, and what the model does and does not protect against.

Everabyte uses a **layered encryption architecture**. Files are encrypted by Everabyte's application services before they are written to storage, and Everabyte's storage infrastructure applies an additional, independent layer of encryption at rest. Objects are therefore protected through their whole lifecycle: in transit over TLS, in the application layer, and at rest.

Decryption happens in exactly three settings, and this page names all of them:

1. **Owner-authorized operations.** Downloads, version restorations, and recovery flows run only in response to an authenticated request the account owner's permissions permit. No key material is used and no content is decrypted outside these requests — and a restoration itself promotes stored ciphertext without decrypting it; only downloads deliver plaintext.
2. **Owner-configured verification.** Backup recoverability tests decrypt sampled restore-point content only when the account owner has enabled them on a backup job, with a schedule and sample size the owner sets.
3. **Platform maintenance.** The scheduled integrity pass described below decrypts stored objects inside controlled internal services. It runs on Everabyte's own schedule, without a per-object owner action: what authorizes it is the platform's published maintenance policy, not an owner request. This is a disclosed deviation from a stricter reading of owner authorization, stated here plainly.

There is no fourth category. No operator or administrator can interactively read file content, and there is no discretionary decryption path.

This page describes the model as implemented. It is deliberately precise about what the encryption model does and does not protect against, because the difference matters for your own security review.

## The encryption pipeline

At a high level, for every file version:

1. A per-file AES key is derived from a hybrid key encapsulation step.
2. The file is encrypted with **AES-256-GCM** in streaming mode, in 64 KB chunks.
3. Each chunk is authenticated as it is written; tags are verified as it is read.
4. The encrypted file and its per-file key envelope are stored.
5. The AES key itself is never persisted. It is recomputed on demand from the envelope and the owning key chain.
6. Once written, the stored object is additionally protected by the storage infrastructure's independent encryption-at-rest layer.

Because encryption is streaming, the server does not buffer a whole object in memory to process it. This is what makes large uploads and range downloads work without weakening the encryption.

## Key hierarchy

| Layer | Material | Where it lives | Rotation |
| - | - | - | - |
| Infrastructure master keys | Versioned platform master keys | Platform environment configuration, never in the database | Offline migration re-wraps key chains under the new version, with dry-run, backup, and verification modes |
| User HPKE key chain | X25519 private key + ML-KEM-768 private key, wrapped at rest under a per-user key-encryption secret held in the database | Database | Master-key rotation re-wraps the chain's key-encryption secret; the chain key pair itself is not rotated. The user-held recovery phrase restores the same key pair after loss |
| Per-file envelope | X25519 encapsulation plus an ML-KEM-768 encapsulation wrapping that version's AES key | Database, one envelope per uploaded version | Write-once. Rotating or re-wrapping the owning chain does not touch existing envelopes |
| Per-file AES key | Derived with HKDF from the X25519 and ML-KEM-768 shared secrets | Never persisted; exists in memory only for the duration of a request and is zeroed afterwards | Not applicable — recomputed on every authorized read |
| Storage credentials | Encrypted with AES-256-GCM and additional authenticated data binding them to their scope | Database | Re-entered by an operator during rotation, followed by a cache flush |

Master keys wrap the user key chains' key-encryption secret; the user key chains wrap the per-file envelopes; the envelopes wrap the per-file AES keys. The recovery passphrase is separate client-held material that can restore a lost key chain. Each level is distinct and must not be described interchangeably.

The `hybrid-sse-v1` string you may see in internal metadata is the scheme identifier of the hybrid encapsulation and the label used inside the HKDF derivation. It is a protocol identifier, not a product claim. Renaming it would break decryption of existing objects.

## Hybrid post-quantum key encapsulation

Per-file keys are wrapped using two mechanisms together:

* **X25519**, a widely deployed elliptic-curve Diffie-Hellman function.
* **ML-KEM-768**, a post-quantum key encapsulation mechanism.

The file key is derived from both shared secrets, so an attacker would need to break both to recover a file key from an envelope. The hybrid design pairs a classical mechanism with a post-quantum one; it is not an absolute quantum-safety guarantee. It also does not change who is authorized to request a decryption.

## The recovery phrase

Users can hold a BIP39 recovery phrase that wraps their private key **in the browser**. The mnemonic never reaches the backend; the platform stores only the wrapped key material, a derivation salt, and a fingerprint of the phrase.

Its function is specific:

* The recovery phrase restores your key chain through the platform's recovery flow, verified with a proof derived from the phrase.
* It is distinct from the master keys, from the per-file keys, and from the decryption key it protects. It is not a second copy of your files.
* An ordinary password reset by email does not disturb the key chain, so file access continues afterwards.
* The phrase must still be treated as a high-value secret by the user.

## Encryption in transit

Traffic between clients and Everabyte is served over TLS. Do not terminate TLS with an untrusted certificate or downgrade clients; the API expects HTTPS. Requests between the platform's internal services are authenticated with service credentials and request signing.

## Integrity verification

The platform runs a scheduled integrity pass — an internal maintenance job, executed daily in production — that re-reads a budgeted sample of stored objects and verifies each one by decrypting it inside the platform's services. Per object, the pass recovers the per-file key from the owner's key chain and the object's envelope, verifies every AES-GCM authentication tag while streaming the stored bytes, decompresses, and compares the recomputed plaintext SHA-256 against the value recorded at write time, where one was recorded; objects without a stored anchor are verified by the GCM tags alone. Verification cannot run on ciphertext alone: AES-GCM tag authentication requires the key, and the plaintext-hash comparison requires the decrypted bytes. A weaker ciphertext-only check (hashing stored bytes without keys) would detect storage-layer corruption but could not prove an object still decrypts — that is not what this process does.

**Authorization status of this process.** It runs on the platform's own schedule, is not triggered or configured by the account owner, and there is currently no owner opt-out and no per-object consent. If you read the owner-authorization principle strictly — nothing decrypts without an owner action — this process is an exception to it, disclosed here deliberately rather than phrased away. What constrains it is operational, not cryptographic: a fixed schedule, a per-run object budget, no interactive access to content, results reported to the owner, and each issue recorded in the audit trail.

On a mismatch, the platform alerts the account owner through in-app notification and email, records the event in the audit trail, emits a webhook where one is configured, and exposes status through compliance-gated views; corrupt objects are reported, not silently removed or quarantined.

## Restore testing

Restore verification is owner-consented, which distinguishes it from the scheduled pass. Backup jobs can enable scheduled recoverability tests — the owner chooses whether they run, on what interval, and with what sample size — and a test can also be run on demand from the job's console. A test samples entries from a restore point, decrypts them server-side through the same verification pipeline, and compares each against the hash pinned when the backup was taken; only a fully matching sample marks the restore point as verified. The desktop agent can additionally run restore tests locally: it restores a sampled set into a fresh isolated directory outside the user's restore destination and deletes the directory afterwards. Combined with version history, this is how the platform demonstrates that backups are usable, rather than merely present.

## What the model protects against — and what it does not

| Threat | Covered? |
| - | - |
| Physical theft or decommissioning of storage media | Yes — objects are encrypted at rest |
| Access to stored objects without their keys | Yes — stored objects are ciphertext |
| A compromised API key reading your buckets | No — use scopes and bucket restrictions; they limit blast radius |
| Administrative access to decrypted files outside authorized workflows | No discretionary decryption path exists — decryption runs only inside the workflows named on this page, and sensitive key operations require step-up authentication and are audited |
| A full platform or infrastructure compromise | Not zero-risk — the platform's services hold the key material needed for authorized decryption, so treat full-platform compromise as in scope for your threat model |
| Operations the account owner authorizes | These produce decrypted content by design — downloads deliver the plaintext to the caller. A version restoration is different: it promotes the stored ciphertext without decrypting it, and plaintext appears only when the content is subsequently downloaded |
| Loss of an entire region | No — there is no automatic second copy |
| Client-device risks after a download | No — downloads deliver decrypted content; endpoint security is a shared responsibility |

> [!TIP]
>
> If your compliance requirement is "the storage layer cannot read our data", this architecture satisfies it. If your requirement is "no Everabyte service may ever process decrypted content", state it during onboarding: owner-authorized operations and the scheduled maintenance pass do process decrypted content by design.

## CDN delivery

On enterprise plans, file delivery can optionally go through a CDN, enabled per company with step-up authentication. When enabled, the platform streams decrypted bytes to the edge over a token-protected origin path, and the edge serves the object through signed URLs. Signed-URL validity is configurable per company — 5 minutes to 30 days, 6 hours by default — and edge caches hold the object for up to 30 days under versioned cache keys.

Cache removal is narrower than access removal, and the difference matters:

* **Hard deletes** trigger a best-effort purge of the edge cache.
* **Revoking a share link or a key** stops new signed URLs from being issued and stops new origin fills, but it does not evict bytes already cached at the edge. Cached copies remain until the cache TTL elapses, up to 30 days.
* **Signed-URL expiry alone never removes cached content.** Expiry stops new requests from being accepted; only the TTL or a purge removes the stored copy.

That is a real trade-off: it improves latency, and it means decrypted content exists at the edge for as long as it is cached — including for a window after a revocation. If your threat model excludes that, use the origin stream route and keep CDN delivery disabled for those buckets.

## Design guidance for integrations

* Treat `fileId` and `versionId` as the authoritative identifiers. Filenames are display metadata.
* Do not assume the platform validates a client-supplied checksum. If you need integrity assurance on your side, hash the plaintext yourself and compare after download.
* Do not store encryption key material you obtain from the platform in logs, analytics, or error reports.
* Remember that scopes and bucket restrictions, not encryption, are what limit blast radius from a leaked key.

## Related

> **[Access control](https://docs.everabyte.com/security/access-control.md)**
>
> Scopes, bucket ceilings, and step-up authentication.

> **[Data residency](https://docs.everabyte.com/security/data-residency.md)**
>
> Where objects live and what is not guaranteed.

> **[Compliance](https://docs.everabyte.com/security/compliance.md)**
>
> What the platform can and cannot attest to.

> **[Versions and restore](https://docs.everabyte.com/storage/versions-and-restore.md)**
>
> How encryption interacts with version history.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.