Logo

Security & Privacy Whitepaper (Overview)Chapter 5

Chapter 5 Cryptography & Key Management

This chapter describes FileBolt's end-to-end encryption (E2EE) and zero-knowledge boundary, and specifies cryptoVersion=v1 parameters, encoding rules, failure modes, and client constraints. Keys are generated and used on the client; the server and object storage handle only ciphertext chunks and required metadata.

5.0 Summary

  • The system MUST NOT receive, store, or log decryption keys (CEK). CEK material is carried only in the URL fragment (# part), which is not sent to the server in HTTP requests.
  • Encryption uses AES-128-GCM (AEAD). Each file uses an independent CEK (16 bytes). Chunk size is fixed (e.g., 16MB).
  • v1 IV construction: IV = noncePrefix(8B) || uint32_be(chunkIndex)(4B). AAD binds transferId, fileId, and chunkIndex to prevent context swapping and replay.
  • Server tokens only control ciphertext access and expire; they do not grant decryption capability.

5.1 Transport encryption (TLS)

5.1.1 Security objective

  • Prevent eavesdropping and tampering on upload/download/API links.
  • Protect tokens and ciphertext in transit.

5.1.2 Security policy

  • The system MUST serve all pages and APIs over HTTPS only.
  • The system SHOULD prefer TLS 1.3 and support TLS 1.2 as needed; weak protocols/ciphers MUST be disabled.
  • The system MUST enable HSTS with a reasonable max-age.

5.2 Chunk encryption (AES-128-GCM)

5.2.1 Design notes

  • Files are split into fixed-size chunks; each chunk is encrypted independently to support parallel transfer and resumability.
  • AEAD authentication protects integrity; any authentication failure MUST fail closed.

5.2.2 Security policy

  • Each file MUST use a distinct CEK (16 bytes).
  • IV MUST be unique per (file, chunkIndex). v1 uses noncePrefix + chunkIndex encoding.
  • AAD MUST include (transferId, fileId, chunkIndex) to bind ciphertext to its context.

5.3 Zero-knowledge link model

5.3.1 Key constraints

  • CEK (or derivation material) MUST be carried only in the URL fragment and MUST NOT be included in query params or headers.
  • The server MUST NOT log fragments; logs MUST be sanitized to avoid accidental capture.
  • Referrer policy SHOULD prevent fragment leakage via outbound navigation (see Chapter 9).

5.4 Key generation & handling

  • Keys MUST be generated using a cryptographically secure RNG (WebCrypto).
  • Keys SHOULD be kept in memory only and cleared when no longer needed.
  • Clients MUST NOT persist CEK in server-visible locations (e.g., cookies, query params).

5.5 Encoding & parameters

  • cryptoVersion=v1 identifies algorithm suite and IV/AAD rules.
  • Manifest MUST include required public parameters (chunk size/count, noncePrefix, fileId mapping) but MUST NOT include CEK.

5.6 Failure modes (fail closed)

  • On decryption failure or AEAD authentication failure, clients MUST abort and MUST NOT output partial plaintext.
  • On parameter mismatch (transferId/fileId/chunkIndex), clients MUST fail closed and SHOULD report an actionable error.

5.7 Related Claim IDs