wiki/appdoc/doc_security_key_management.md

PowerOn Key Management Specification

1. Objective

PowerOn requires a secure, pragmatic key management system that:

• Encrypts all sensitive configuration values (API keys, passwords, tokens) in configuration files
• Maintains strict environment separation (dev/int/prod) with different master keys
• Enables local development without internet dependency
• Provides simple developer workflow for adding/updating encrypted keys
• Ensures production security with external master key storage

2. Key Management Logic

2.1 Master Key Storage Strategy

Development Environment:

• Master key stored locally in <key file path>/key.txt file
• File format: env = 256bit-base64-encoded-key
• Never committed to Git repository
• Accessible for local development without internet

Production/Integration Environments:

• Master key stored as Azure environment variable
• Variable name defined by APP_KEY_SYSVAR configuration - to set to HIDDEN!
• Fallback to file-based storage if environment variable not found
• Complete separation from development keys

2.2 Encryption/Decryption Process

Encryption Process:

1. Key Detection: Identify if value needs encryption (ends with _SECRET)
2. Master Key Retrieval: Load appropriate master key based on environment
3. Key Derivation: Use PBKDF2 to derive encryption key from master key
4. Value Encryption: Encrypt using AES-256-GCM via Fernet
5. Prefix Addition: Add environment-specific prefix (DEV_ENC:, INT_ENC:, PROD_ENC:)
6. Storage: Save encrypted value to configuration file

Decryption Process:

1. Prefix Detection: Check if value starts with environment prefix
2. Environment Validation: Ensure prefix matches current environment
3. Master Key Retrieval: Load master key for current environment
4. Key Derivation: Derive same encryption key using PBKDF2
5. Value Decryption: Decrypt using Fernet
6. Return: Provide plain text value to application

2.3 Environment-Specific Master Keys

Key Format in key.txt:

prod = 256bit-key-for-config-encryption
int = 256bit-key-for-config-encryption  
dev = 256bit-key-for-config-encryption

Environment Variable (Azure):

• Variable name: Value of APP_KEY_SYSVAR (e.g., CONFIG_KEY)
• Value: 256-bit base64-encoded master key
• Used for production and integration environments

3. Developer Workflow

3.1 Adding New Encrypted Keys

Step 1: Identify Secret Value

• Locate configuration value ending with _SECRET
• Determine if it's text or JSON format

Step 2: Use Encryption Tool

cd gateway
python tool_encrypt_config_value.py --value "my_secret_value" --env dev

Step 3: Update Configuration File

• Copy encrypted output to appropriate .env file
• Replace plain text value with encrypted version

Step 4: Verify

• Restart application
• Confirm secret is properly decrypted and accessible

3.2 Development Environment Setup

Prerequisites:

1. Master key file exists at <key file path>/key.txt
2. Environment variable APP_KEY_SYSVAR points to key file path
3. Environment variable APP_ENV_TYPE set to dev

Setup Steps:

1. Generate Master Key: Create secure 256-bit key for development
2. Create Key File: Save key in <key file path>/key.txt with dev = <key>
3. Configure Environment: Set APP_KEY_SYSVAR to key file path
4. Test Encryption: Use tool to encrypt a test value
5. Verify Decryption: Confirm application can decrypt values
6. Share key file with developer: Share the key file with the developer

3.3 Azure Environment Setup

Production Environment:

1. Generate Production Key: Create unique 256-bit master key
2. Store in Azure: Add as environment variable with name from APP_KEY_SYSVAR
3. Deploy: Application automatically uses Azure environment variable

Integration Environment:

1. Generate Integration Key: Create unique 256-bit master key
2. Store in Azure: Add as environment variable
3. Deploy: Application uses integration-specific master key

4. Security Considerations

4.1 Master Key Protection

• Never log master keys in application logs
• Use secure key derivation (PBKDF2 with 100,000 iterations)
• Environment isolation prevents cross-environment decryption
• External storage keeps keys out of code repository

4.2 Encryption Security

• AES-256-GCM encryption provides authenticated encryption
• Unique salt per environment prevents key reuse
• Base64 encoding for safe storage in configuration files
• Environment prefixes prevent accidental cross-environment usage

4.3 Key Rotation Strategy

• Regular rotation of master keys: No rotation, as keys are rotated

5. Configuration File Structure

5.1 Environment Files

gateway/
├── .env             # Active environment file for the application
├── env_dev.env      # Environment file for development including encrypted keys (*_SECRET)
├── env_int.env      # Environment file for integration including encrypted keys (*_SECRET)  
├── env_prod.env     # Environment file for production including encrypted keys (*_SECRET)
└── config.ini       # Non-sensitive configuration parts for all environments    

5.2 Encrypted Value Format

# Text secrets
API_KEY_SECRET = DEV_ENC:gAAAAABh...encrypted_value...

# JSON secrets  
SERVICE_ACCOUNT_SECRET = DEV_ENC:gAAAAABh...encrypted_json...

6. Monitoring and Alerts

• Track decryption attempts per environment
• Alert on failed decryptions or missing keys
• Log security events (without exposing keys)

7. Best Practices

7.1 Developer Guidelines

• Always use encryption tool for new secrets
• Never commit plain text secrets to repository
• Test decryption after encryption
• Use environment-specific tools for each environment

7.2 Production Guidelines

• Secure key storage in Azure Key Vault (future enhancement)
• Audit logging for all key operations
• Documentation updates for any changes