diff options
Diffstat (limited to 'src/content/docs/advanced/app-data-storage.md')
| -rw-r--r-- | src/content/docs/advanced/app-data-storage.md | 63 |
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. |