# PowerOn Key Management Implementation Specification

## 1. Implementation Overview

This document outlines the step-by-step implementation of the PowerOn Key Management system, building upon the existing configuration framework while adding robust encryption/decryption capabilities.

## 2. Core Components to Implement

### 2.1 Enhanced Configuration Module (`gateway/modules/shared/configuration.py`)

**Current State:**
- Basic configuration loading from `config.ini` and `.env` files
- Simple `handleSecretText()` and `handleSecretJson()` functions (no encryption)
- Global `APP_CONFIG` object for configuration access

**Required Enhancements:**
1. **Master Key Management Functions**
2. **Encryption/Decryption Functions** 
3. **Environment Detection Logic**
4. **Enhanced Secret Handling Functions**

### 2.2 Encryption Tool (`gateway/tool_encrypt_config_value.py`)

**Purpose:** Command-line tool for developers to encrypt secret values
**Features:**
- Interactive and command-line modes
- Support for text and JSON values
- Environment-specific encryption
- Decryption testing capability

### 2.3 Master Key Generation (`gateway/generate_master_keys.py`)

**Purpose:** Generate secure master keys for all environments
**Output:** Update `local/key.txt` with new secure keys

## 3. Detailed Implementation Steps

### Step 1: Add Required Dependencies

**File:** `gateway/requirements.txt`
**Action:** Add cryptography library
```txt
cryptography>=41.0.0
```

### Step 2: Implement Master Key Management

**File:** `gateway/modules/shared/configuration.py`

**Functions to Add:**
1. `_get_master_key() -> bytes`
   - Read from environment variable (Azure)
   - Fallback to file-based storage (`local/key.txt`)
   - Parse environment-specific key from file
   - Error handling for missing keys

2. `_derive_encryption_key(master_key: bytes) -> bytes`
   - Use PBKDF2 with SHA-256
   - Fixed salt for consistency
   - 100,000 iterations
   - Return 32-byte key for Fernet

3. `_is_encrypted_value(value: str) -> bool`
   - Check for environment-specific encryption prefixes (e.g., `{ENV}_ENC:`)
   - Dynamically detect prefixes based on current environment
   - Return True if encrypted, False otherwise

4. `_get_encryption_prefix(env_type: str) -> str`
   - Generate environment-specific prefix dynamically
   - Format: `{ENV_TYPE}_ENC:` (uppercase environment type)
   - Support any environment type (dev/int/prod/staging/etc.)

5. `_check_decryption_rate_limit(env_type: str) -> bool`
   - Track decryption attempts per environment
   - Enforce maximum 1 decryption per second
   - Return True if allowed, False if rate limited
   - Log rate limit violations for security monitoring

### Step 3: Implement Encryption/Decryption Functions

**File:** `gateway/modules/shared/configuration.py`

**Functions to Add:**
1. `encrypt_value(value: str, env_type: str = None) -> str`
   - Get master key for specified environment
   - Derive encryption key using PBKDF2
   - Encrypt using Fernet (AES-256-GCM)
   - Add dynamically generated environment-specific prefix
   - Return base64-encoded encrypted value

2. `decrypt_value(encrypted_value: str) -> str`
   - Check decryption rate limit for current environment
   - Validate encryption prefix (dynamic environment detection)
   - Extract encrypted portion
   - Get master key for current environment
   - Derive decryption key
   - Decrypt using Fernet
   - Return plain text value

### Step 4: Enhance Secret Handling Functions

**File:** `gateway/modules/shared/configuration.py`

**Modify Existing Functions:**
1. `handleSecretText(value: str) -> str`
   - Check if value is encrypted
   - Decrypt if encrypted, return as-is if not
   - Maintain backward compatibility

2. `handleSecretJson(value: str) -> str`
   - Check if value is encrypted
   - Decrypt if encrypted
   - Validate JSON format after decryption
   - Return decrypted JSON string

### Step 5: Create Encryption Tool

**File:** `gateway/tool_encrypt_config_value.py`

**Features:**
- Command-line interface with argparse
- Support for `--value`, `--file`, `--env` parameters
- Interactive mode for user input
- JSON validation for structured data
- Decryption testing with `--decrypt` flag
- Usage examples and help text

**Usage Examples:**
```bash
# Interactive mode
python tool_encrypt_config_value.py

# Command line mode
python tool_encrypt_config_value.py --value "my_secret" --env dev

# File input
python tool_encrypt_config_value.py --file "service_account.json" --env prod

# Test decryption
python tool_encrypt_config_value.py --decrypt "DEV_ENC:gAAAAABh..."
```

### Step 6: Create Master Key Generator

**File:** `gateway/generate_master_keys.py`

**Features:**
- Generate cryptographically secure 256-bit keys
- Base64 encoding for safe storage
- Update `local/key.txt` file
- Support for all environments (dev/int/prod)

**Output Format:**
```
prod = <256-bit-base64-key>
int = <256-bit-base64-key>
dev = <256-bit-base64-key>
```

### Step 7: Update Configuration Loading

**File:** `gateway/modules/shared/configuration.py`

**Modifications:**
1. **Import Statements:** Add cryptography imports
2. **Error Handling:** Robust error handling for key operations
3. **Logging:** Security-aware logging (no key exposure)
4. **Backward Compatibility:** Support both encrypted and plain text values

### Step 8: Environment Configuration Updates

**Files to Update:**
- `gateway/env_dev.env`
- `gateway/env_int.env` 
- `gateway/env_prod.env`

**Changes:**
1. **Add Key Configuration:**
   ```env
   APP_KEY_SYSVAR = D:/Athi/Local/Web/poweron/local/key.txt  # dev
   APP_KEY_SYSVAR = CONFIG_KEY  # int/prod
   ```

2. **Encrypt Existing Secrets:**
   - Identify all `_SECRET` values
   - Encrypt using appropriate environment tool
   - Replace plain text with encrypted values

### Step 9: Testing and Validation

**Test Cases:**
1. **Encryption Tool Testing:**
   - Test text value encryption
   - Test JSON value encryption
   - Test decryption functionality
   - Test error handling

2. **Configuration Loading Testing:**
   - Test encrypted value decryption
   - Test plain text value handling
   - Test environment-specific keys
   - Test error scenarios

3. **Environment Testing:**
   - Test development environment
   - Test integration environment
   - Test production environment
   - Test cross-environment security

### Step 10: Documentation and Training

**Documentation Updates:**
1. **Developer Guide:** How to use encryption tool
2. **Deployment Guide:** Azure environment setup
3. **Troubleshooting Guide:** Common issues and solutions
4. **Security Guide:** Best practices and guidelines

## 4. Implementation Order

### Phase 1: Core Infrastructure
1. Add cryptography dependency
2. Implement master key management functions
3. Implement encryption/decryption functions
4. Create master key generator

### Phase 2: Tool Development
1. Create encryption tool
2. Test tool functionality
3. Create usage documentation

### Phase 3: Integration
1. Enhance secret handling functions
2. Update configuration loading
3. Test backward compatibility

### Phase 4: Environment Setup
1. Generate master keys
2. Update environment configurations
3. Encrypt existing secrets
4. Test in all environments

### Phase 5: Validation
1. Comprehensive testing
2. Security validation
3. Performance testing
4. Documentation completion

## 5. Security Considerations

### 5.1 Code Security
- **No hardcoded keys** in source code
- **Secure random generation** for master keys
- **Proper key derivation** using PBKDF2
- **Environment isolation** for key access

### 5.2 Runtime Security
- **Memory protection** for sensitive data
- **Secure logging** (no key exposure)
- **Error handling** without information leakage
- **Input validation** for all operations

### 5.3 Deployment Security
- **Azure environment variables** for production keys
- **File permissions** for local key storage
- **Access control** for key management tools
- **Audit logging** for key operations

## 6. Error Handling Strategy

### 6.1 Master Key Errors
- **Missing Key:** Clear error message with resolution steps
- **Invalid Format:** Validation with helpful error messages
- **Access Denied:** File permission error handling
- **Environment Mismatch:** Cross-environment usage prevention

### 6.2 Encryption Errors
- **Invalid Input:** Input validation and error messages
- **Encryption Failure:** Cryptographic error handling
- **Format Errors:** Base64 encoding/decoding error handling
- **Environment Errors:** Wrong environment key usage
- **Invalid Prefix:** Unrecognized encryption prefix format

### 6.3 Rate Limiting Errors
- **Rate Limit Exceeded:** "Decryption rate limit exceeded for environment '{env}'"
- **Throttling:** Exponential backoff for repeated violations
- **Monitoring:** Log all rate limit violations for security analysis
- **Recovery:** Automatic retry after rate limit period expires

### 6.4 Configuration Errors
- **Missing Configuration:** Default value handling
- **Invalid Values:** Configuration validation
- **File Errors:** File access error handling
- **Parsing Errors:** Configuration file parsing errors

## 7. Performance Considerations

### 7.1 Key Derivation
- **PBKDF2 Iterations:** Balance security vs. performance
- **Key Caching:** Consider caching derived keys
- **Memory Usage:** Minimize memory footprint

### 7.2 Encryption Operations
- **Batch Operations:** Support multiple value encryption
- **Async Operations:** Consider async for large values
- **Memory Management:** Proper cleanup of sensitive data

### 7.3 Configuration Loading
- **Lazy Loading:** Load keys only when needed
- **Caching:** Cache decrypted values appropriately
- **File Monitoring:** Efficient file change detection

### 7.4 Decryption Rate Limiting
- **Rate Limiting:** Maximum 1 decryption per second per environment
- **Tracking:** Monitor decryption attempts per environment
- **Throttling:** Implement exponential backoff for rate limit violations
- **Logging:** Log rate limit violations for security monitoring

## 8. Migration Strategy

### 8.1 Backward Compatibility
- **Dual Support:** Support both encrypted and plain text values
- **Gradual Migration:** Migrate secrets incrementally
- **Rollback Capability:** Easy rollback if issues arise

### 8.2 Migration Steps
1. **Deploy Enhanced Code:** With backward compatibility
2. **Generate Master Keys:** For all environments
3. **Encrypt Secrets:** Using encryption tool
4. **Update Configurations:** Replace plain text values
5. **Test Thoroughly:** In all environments
6. **Remove Plain Text:** After successful validation

### 8.3 Validation
- **Functionality Testing:** Ensure all features work
- **Security Testing:** Verify encryption/decryption
- **Performance Testing:** Check for performance impact
- **Integration Testing:** Test with existing applications