From d3038e9118e0ed82893d7b7510a37c79d590a1da Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sat, 16 Nov 2024 18:09:03 +0100 Subject: [PATCH 1/8] add concept of master key encryption key --- docs/concepts/master-key-encryption-key.md | 95 ++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/concepts/master-key-encryption-key.md diff --git a/docs/concepts/master-key-encryption-key.md b/docs/concepts/master-key-encryption-key.md new file mode 100644 index 0000000..74f34b2 --- /dev/null +++ b/docs/concepts/master-key-encryption-key.md @@ -0,0 +1,95 @@ +# Using a Master Key to Encrypt Cryptographic Material + +## Overview + +In cryptographic systems, **master keys** (also called **Key Encryption Keys (KEK)**) are used to securely encrypt and protect other cryptographic keys, such as **data encryption keys (DEKs)**, which are in turn used to encrypt data (e.g., BLOBs or metadata). This hierarchical key management structure is essential for managing keys securely, especially in systems that handle large volumes of sensitive data. + +### Key Concepts + +- **Master Key (KEK)**: A key used to encrypt (wrap) other keys, ensuring that the actual data encryption keys (DEKs) are never exposed in plaintext. +- **Data Encryption Key (DEK)**: A key used for encrypting actual data (such as BLOBs or metadata). DEKs are often symmetric keys (e.g., AES-256). +- **Key Wrapping**: The process of encrypting one key (the DEK) using another key (the master key). + +## Step-by-Step Process + +### 1. **Generate a Master Key** +The **master key** is typically stored in a secure Key Management Service (KMS) like **AWS KMS**, **Azure Key Vault**, or **Google Cloud KMS**. + +- **Key Type**: The master key can be **symmetric** (e.g., AES-256) or **asymmetric** (e.g., RSA, ECC). + +### 2. **Generate Data Encryption Keys (DEKs)** +A **data encryption key** (DEK) is generated for each encryption operation. These DEKs are used to encrypt specific data, such as metadata or BLOBs. + +- **Key Type**: DEKs are usually **symmetric** keys, commonly **AES** keys (e.g., AES-256). + +### 3. **Wrap (Encrypt) the DEK with the Master Key** +The **master key** is used to **wrap** or **encrypt** the data encryption key (DEK). + +- **Symmetric Key Wrapping**: The DEK is encrypted using the master key (AES). +- **Asymmetric Key Wrapping**: The DEK is encrypted using the master key's **private key** (RSA, ECC). + +### 4. **Store the Encrypted Data and Wrapped DEK** +- **Encrypted Data**: The data (e.g., BLOBs or metadata) is encrypted using the DEK. +- **Wrapped DEK**: The DEK is stored in its encrypted (wrapped) form, never in plaintext, alongside or separately from the encrypted data. + +### 5. **Decrypting the Data** +When you need to access the encrypted data, follow these steps: +1. **Retrieve the wrapped DEK** from storage. +2. **Unwrap** the DEK using the **master key**. +3. Use the DEK to decrypt the encrypted data (BLOBs or metadata). + +### 6. **Key Rotation and Expiration** +To ensure long-term security, periodically rotate both the master key and the data encryption keys: +- **Master Key Rotation**: Replace the old master key with a new one. Rewrap the DEKs with the new master key. +- **DEK Rotation**: Generate new DEKs, encrypt new data with them, and wrap them with the master key. + +## Example Use Case + +### Master Key and DEK Management +1. **Master Key (KEK)**: AES-256 key stored in AWS KMS or Azure Key Vault. +2. **Data Encryption Key (DEK)**: AES-256 key generated to encrypt a specific BLOB. +3. **Process**: + - **Wrap DEK**: Use the master key (AES-256) to encrypt the DEK. + - **Encrypt Data**: Use the DEK to encrypt the data (BLOB or metadata). + - **Store Data**: Store the encrypted data and the wrapped DEK in your storage system. + +4. **Decryption**: + - **Unwrap DEK**: Use the master key to unwrap (decrypt) the DEK. + - **Decrypt Data**: Use the DEK to decrypt the BLOB. + +## Advantages of Using a Master Key to Protect Other Cryptographic Material + +1. **Separation of Duties**: The master key is securely stored in a key management system, while only the wrapped DEKs are exposed. +2. **Key Lifecycle Management**: Easier key rotation and management of DEKs without directly exposing them. +3. **Minimization of Key Exposure**: Only the wrapped keys are stored, reducing the risk of plaintext keys being exposed. +4. **Performance**: Symmetric encryption (AES) of DEKs is much more efficient for large volumes of data than using asymmetric encryption. +5. **Compliance and Security**: Ensures compliance with security standards like PCI DSS, GDPR, and HIPAA by keeping data and keys secure. + +## Cloud Provider Support for Key Wrapping + +### AWS Key Management Service (KMS) +- Supports **symmetric (AES)** and **asymmetric (RSA, ECC)** key wrapping. +- The `Encrypt` and `Decrypt` API calls are used to wrap and unwrap DEKs. + +### Azure Key Vault +- Supports **symmetric (AES)** and **asymmetric (RSA, ECC)** key wrapping. +- The `wrapKey` and `unwrapKey` API calls are used for key wrapping. + +### Google Cloud Key Management Service (KMS) +- Supports **symmetric (AES)** and **asymmetric (RSA)** key wrapping. +- The `Encrypt` and `Decrypt` API calls are used for key wrapping and unwrapping. + +## Example: Key Wrapping and Encryption in AWS KMS + +```bash +# Generate a DEK for data encryption +aws kms generate-data-key --key-id --key-spec AES_256 + +# Encrypt data with the DEK (AES-256) +aws s3 cp s3:/// --sse AES256 --sse-kms-key-id + +# Wrap the DEK using the master key (AES-256) +aws kms encrypt --key-id --plaintext --output text + +# Store the wrapped DEK securely alongside the encrypted data +``` \ No newline at end of file From 97d6683cc27bf5b93b8497b7f8280429a103f8cb Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 14:42:42 +0100 Subject: [PATCH 2/8] add ERD --- docs/diagrams/erd.mmd | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/diagrams/erd.mmd diff --git a/docs/diagrams/erd.mmd b/docs/diagrams/erd.mmd new file mode 100644 index 0000000..68bfc3f --- /dev/null +++ b/docs/diagrams/erd.mmd @@ -0,0 +1,35 @@ +erDiagram + CRYPTOGRAPHIC_KEY { + string key_id PK + string key_value + string key_type + datetime created_at + datetime expires_at + string user_id FK + } + + METADATA { + string metadata_id PK + string blob_id FK + string key_id FK + datetime created_at + datetime updated_at + string encryption_algorithm + string content_type + int size + string user_id FK + } + + BLOB { + string blob_id PK + string blob_storage_path + datetime upload_time + string user_id FK + string file_name + int file_size + string file_type + } + + CRYPTOGRAPHIC_KEY ||--o| METADATA : "used in" + CRYPTOGRAPHIC_KEY ||--o| BLOB : "associated with" + BLOB ||--o| METADATA : "has metadata" From 96241f3849368032199cda1c5d687101027e2bd1 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 14:52:46 +0100 Subject: [PATCH 3/8] add use case overview --- docs/diagrams/use-case-overview.mmd | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 docs/diagrams/use-case-overview.mmd diff --git a/docs/diagrams/use-case-overview.mmd b/docs/diagrams/use-case-overview.mmd new file mode 100644 index 0000000..79c3dae --- /dev/null +++ b/docs/diagrams/use-case-overview.mmd @@ -0,0 +1,23 @@ +graph TD; + +Admin["Administrator"] +LoggedInUser["Logged In User"] + +Admin --> UC1["Create, Rotate, Delete Keys"] +Admin --> UC2["Manage KeyVault"] +Admin --> UC3["View and Delete Blobs"] +Admin --> UC4["Logout"] + +LoggedInUser --> UC5["Create Own Keys"] +LoggedInUser --> UC6["Upload, Update, Delete Own Files (Blobs)"] +LoggedInUser --> UC7["Download Own Files (Blobs)"] +LoggedInUser --> UC8["View Own File Metadata"] +LoggedInUser --> UC9["Encrypt/Decrypt Own Files"] +LoggedInUser --> UC10["Hash Own Files"] +LoggedInUser --> UC11["Verify File Signature"] +LoggedInUser --> UC12["View Public Files (Blobs)"] +LoggedInUser --> UC13["Download Public Files (Blobs)"] +LoggedInUser --> UC14["Logout"] + +classDef actor fill:#ADD8E6,stroke:#333,stroke-width:2px; +class Admin,LoggedInUser actor; \ No newline at end of file From 282eb2992cb5d482eb56861d5f989411413aaab1 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 15:13:50 +0100 Subject: [PATCH 4/8] modify bullet point --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9985027..cc50f1e 100644 --- a/README.md +++ b/README.md @@ -28,7 +28,7 @@ RESTful Web API for managing cryptographic keys and securing data at rest (metad - [ ] **Manage cryptographic material**: Enable management of private/public key pairs and symmetric keys (generation, import/export, rotation, etc.). - [ ] **Key management lifecycle**: Implement key lifecycle management (generation, rotation, revocation, expiration). - [ ] **Secure file storage integration**: Provide mechanisms to securely store encrypted files in BLOB storage (e.g. AWS S3, Azure Blob Storage, Google Cloud Storage). -- [ ] **Access control**: Implement role-based access control (RBAC) for APIs ensuring that only authorized users can perform operations on cryptographic material. +- [ ] **Access control**: Implement relationship-based access control (ReBAC) for APIs, ensuring that users can only perform operations on cryptographic material based on their defined relationships and permissions within the system. ### Non-functional From 99b008500d17f041e005d275d66b7fcea87ee8c3 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 15:29:24 +0100 Subject: [PATCH 5/8] add reference --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index cc50f1e..48a64f2 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ RESTful Web API for managing cryptographic keys and securing data at rest (metad - [OpenSSL with libp11 for Signing, Verifying and Encrypting, Decrypting](https://docs.yubico.com/hardware/yubihsm-2/hsm-2-user-guide/hsm2-openssl-libp11.html#rsa-pkcs) - [pkcs11-tool usage](https://docs.nitrokey.com/nethsm/pkcs11-tool#id1) +- [OpenFGA online editor](https://play.fga.dev/sandbox/?store=github) ## Features From a5058aeeb46b85cc74b81691f18cde2279b29c28 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 15:29:35 +0100 Subject: [PATCH 6/8] remove gitkeep --- docs/diagrams/.gitkeep | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 docs/diagrams/.gitkeep diff --git a/docs/diagrams/.gitkeep b/docs/diagrams/.gitkeep deleted file mode 100644 index e69de29..0000000 From e190eb4f6c110411ad05ac1b9b797e2a7f350f39 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 16:13:40 +0100 Subject: [PATCH 7/8] modify usecase overview --- docs/diagrams/use-case-overview.mmd | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/docs/diagrams/use-case-overview.mmd b/docs/diagrams/use-case-overview.mmd index 79c3dae..096d7a6 100644 --- a/docs/diagrams/use-case-overview.mmd +++ b/docs/diagrams/use-case-overview.mmd @@ -9,15 +9,17 @@ Admin --> UC3["View and Delete Blobs"] Admin --> UC4["Logout"] LoggedInUser --> UC5["Create Own Keys"] -LoggedInUser --> UC6["Upload, Update, Delete Own Files (Blobs)"] -LoggedInUser --> UC7["Download Own Files (Blobs)"] +LoggedInUser --> UC6["Upload, Update, Delete Own Blobs"] +LoggedInUser --> UC7["Download Own Blobs"] LoggedInUser --> UC8["View Own File Metadata"] LoggedInUser --> UC9["Encrypt/Decrypt Own Files"] LoggedInUser --> UC10["Hash Own Files"] LoggedInUser --> UC11["Verify File Signature"] -LoggedInUser --> UC12["View Public Files (Blobs)"] -LoggedInUser --> UC13["Download Public Files (Blobs)"] -LoggedInUser --> UC14["Logout"] +LoggedInUser --> UC12["View Public Blobs"] +LoggedInUser --> UC13["Download Public Blobs"] +LoggedInUser --> UC14["View Blobs with granted permissions"] +LoggedInUser --> UC15["Download Blobs with granted permissions"] +LoggedInUser --> UC16["Logout"] classDef actor fill:#ADD8E6,stroke:#333,stroke-width:2px; class Admin,LoggedInUser actor; \ No newline at end of file From cea8b0236f6ed770d33be6d4d6b7599fdcedc1b7 Mon Sep 17 00:00:00 2001 From: Marvin Gajek Date: Sun, 17 Nov 2024 16:21:11 +0100 Subject: [PATCH 8/8] add initial relationship based model based on OpenFGA format --- docs/diagrams/openfga.dsl | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) create mode 100644 docs/diagrams/openfga.dsl diff --git a/docs/diagrams/openfga.dsl b/docs/diagrams/openfga.dsl new file mode 100644 index 0000000..db1f85e --- /dev/null +++ b/docs/diagrams/openfga.dsl @@ -0,0 +1,34 @@ +model + schema 1.1 + +type user + +type blob + relations + # Permissions related to file management + define can_manage_all_blobs: admin + define can_manage_own_blobs: owner + define can_download_blobs_with_given_permission: grantee + define can_view_blobs_with_given_permission: grantee + + # Cryptographic actions + define create_own_cryptographic_keys: owner + define encrypt_decrypt_own_files: owner + define generate_signature_for_own_files: owner + define verify_file_signature: owner or grantee # Public key verification is possible for grantee + + # Access control for owners and grantees + define can_grant_access_to_download_owned_blobs: owner + define can_grant_access_to_view_owned_blobs: owner + + # Ownership and user roles + define owner: [user] + define grantee: [user] # A user who has been granted permissions for an owner's blob + define admin: [user] # Admin can manage all blobs, including cryptographic actions + + # Additional clarifications + # - Admin has full control over all blobs + # - Owner controls access to their own blob, including granting permissions + # - Grantee has permission to download or view blobs if granted by the owner + + # In order to visualize the relationship based model visit https://play.fga.dev/sandbox/?store=github and paste in this content