dsfx/docs/adr/0003-key-management-strategy.md

ADR-0003: Key Management Strategy

Status

Proposed

Context

A fundamental aspect of our secure file storage system is ensuring that encryption keys remain under the exclusive control of the user. As all file encryption and decryption is performed on the client side (FR-1), it is critical that the key management strategy prevents external exposure and compromise of encryption keys. In addition, our system must provide a secure and efficient method for deriving keys from user inputs such as passphrases, while remaining compatible with our deterministic simulation testing framework to mimic real-world scenarios, including network and disk failure conditions (NFR-1, NFR-2).

The key management approach must also support integration with OS-level keychains or hardware-based key management modules when available, ensuring that keys are stored and accessed in a secure manner, thereby enhancing overall user privacy and data security.

Decision

We will implement a client-side key management strategy based on secure key derivation and strict local storage practices. The strategy will include the following elements:

• Key Derivation Function (KDF): We will use one of the recognized strong key derivation functions such as Argon2, scrypt, or PBKDF2 to derive encryption keys from user-supplied passphrases. This approach aligns with our requirement to derive keys securely on the client side (FR-1, NFR-1) while ensuring that the derivation process is robust against brute-force attacks.

• Local Key Storage: Keys will be managed and stored exclusively on the client. Where possible, integration with OS-level secure keychains or hardware security modules (HSMs) will be provided to further protect key material. This approach bolsters the privacy guarantee by ensuring that keys never leave the user’s controlled environment.

• Deterministic Simulation Support: The key management module will be designed to allow deterministic simulation of key derivation and storage processes. Testing will simulate conditions such as network and disk latencies and possible failures to ensure that the key management functions remain reliable under all conditions (NFR-2, NFR-6).

• Auditability and Transparency: Any operation involving key management (such as key derivation, updates, and revocations) will generate audit logs that are tamper-evident (FR-6, NFR-5). This ensures that every change in key status is tracked, and the process remains transparent and verifiable to the user.

Consequences

• Advantages:

  • Enhanced Security: By deriving and managing keys entirely on the client side and leveraging strong KDFs, the strategy isolates sensitive key material from external exposure, upholding our commitment to rigorous data security (FR-1, NFR-1).
  • User Empowerment: Integration with OS-level keychains or HSMs gives users additional confidence in the security of their keys, strengthening the principle of digital self-ownership.
  • Robust Testing Capability: The designed compatibility with deterministic simulation testing allows for thorough evaluation of key management processes under adverse conditions, ensuring continuous performance and reliability (NFR-2, NFR-6).

• Trade-offs:

  • Performance Impact: Advanced key derivation functions such as Argon2 may introduce additional computational overhead. However, this is a necessary trade-off to ensure strong protection against brute-force attacks.
  • Implementation Complexity: Integrating with multiple potential key storage mechanisms (OS-level or hardware-based modules) may increase the overall complexity of the implementation.
  • Testing Complexity: Simulating the key management process under various network and disk failure scenarios requires careful design of the deterministic testing framework, potentially increasing the testing and validation effort.

References to Requirements

• Functional Requirements:

  • FR-1: Secure file upload & download, ensuring that all encryption and decryption happens on the client, backed by strong key management.
  • FR-6: User control and access management is supported by precise and auditable key management operations.

• Non-Functional Requirements:

  • NFR-1: Security & privacy, which mandates the use of robust cryptographic techniques and secure key management practices.
  • NFR-2: Performance & responsiveness, as the key derivation process should operate efficiently even under simulated network and disk latency conditions.
  • NFR-6: Deployability & maintainability, which requires that key operations be thoroughly testable under deterministic simulation environments to ensure reliability.

Conclusion

The proposed key management strategy, centered on strong, client-side key derivation and secure key storage, meets our core system requirements. It preserves user privacy and data control by ensuring that encryption keys are derived, stored, and managed exclusively on the client. The design’s compatibility with deterministic simulation testing further ensures that key management remains robust under a variety of adverse conditions, fulfilling our mission to create a secure, transparent, and user-controlled file storage system.