docs(advanced): add app data storage documentation

- document application data storage approach and security considerations
- explain data object structure and encryption methods
- describe file layout and access patterns
- include security considerations and key rotation support

1 files changed, 63 insertions, 0 deletions

diff --git a/src/content/docs/advanced/app-data-storage.md b/src/content/docs/advanced/app-data-storage.md
new file mode 100644
index 0000000..10b1c52
--- /dev/null
+++ b/src/content/docs/advanced/app-data-storage.md
@@ -0,0 +1,63 @@
+---
+title: "Application Data Storage"
+sidebar:
+  label: Application Data Storage
+---
+
+GpgFrontend employs a robust and secure approach for storing application data,
+especially for sensitive or dynamic information such as key server settings, key
+generation profiles, and other internal objects.
+
+> Note: Prior to version 2.1.9, application data encryption was handled
+> differently: The reference for each data object was generated by simply
+> computing the SHA-256 hash of the master application key combined with the
+> object name. All objects were encrypted directly with the master key, without
+> per-object key derivation, HMAC, or authenticated encryption modes. Advanced
+> techniques such as HKDF-based key derivation, per-object HMAC, and
+> authenticated encryption (e.g., AES-GCM) were introduced in v2.1.9 for
+> significantly improved security.
+
+## Data Object Structure
+
+- Unique Reference: Each piece of application data is associated with a unique
+  reference, generated using an HMAC-SHA256 digest of the object name (or a
+  random value for unnamed objects) and a legacy key. This ensures both
+  uniqueness and integrity of the data mapping.
+- Per-Object Encryption: Every data object is encrypted individually using a key
+  derived from the current active application secure key and the object’s
+  reference. Key derivation utilizes HKDF-SHA256 for high security and
+  resistance to key reuse attacks.
+- Key Identification: The first part of each stored object file contains an
+  identifier for the key used to encrypt it, allowing for seamless key rotation
+  and backward compatibility.
+- Encryption Algorithms: Actual data encryption uses lightweight, authenticated
+  cryptography (such as AES-GCM or an equivalent mode), ensuring both
+  confidentiality and integrity of application objects.
+
+## File Layout and Access
+
+- Storage Location: All encrypted data objects are stored in the `data_objs/`
+  subdirectory within the application’s data directory.
+- File Naming: Encrypted objects are stored as files named after the hexadecimal
+  encoding of their reference value. This obfuscates file content and prevents
+  direct association with plaintext object names.
+- Data Separation: Data created under different SecureLevels or key environments
+  is logically separated, providing clear isolation between different security
+  contexts.
+- Secure Key Retrieval: On access, the application retrieves the correct
+  encryption key for each data object using its embedded key identifier, and
+  securely derives the per-object key to decrypt or update the content.
+- Atomic Updates: Data updates are handled in a manner that prevents corruption
+  or partial writes, ensuring data integrity even in the event of application or
+  system interruptions.
+
+## Security Considerations
+
+- Strong Isolation: Per-object encryption and unique key derivation mean that
+  compromise of one data object does not impact the security of others.
+- Key Rotation Support: When application keys are rotated, existing objects
+  remain accessible through their associated key identifiers, supporting smooth
+  transitions and automated data migration.
+- User Transparency: All encryption, decryption, and data migration processes
+  are handled transparently by GpgFrontend, requiring no manual intervention
+  from users in regular workflows.