Merge pull request #7 from MGTheTrain/docs

Docs

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
 
@@ -28,7 +29,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
 

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 <MasterKeyId> --key-spec AES_256
+
+# Encrypt data with the DEK (AES-256)
+aws s3 cp <data-file> s3://<bucket-name>/<encrypted-file> --sse AES256 --sse-kms-key-id <DEK>
+
+# Wrap the DEK using the master key (AES-256)
+aws kms encrypt --key-id <MasterKeyId> --plaintext <DEK> --output text
+
+# Store the wrapped DEK securely alongside the encrypted data
+```

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"

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

docs/diagrams/use-case-overview.mmd

@@ -0,0 +1,25 @@
+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 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 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;