wiki/z-archive/implementation/implementation_key_management.md

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

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:

# 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:

   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