wiki/poweron/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**
```bash
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`
4. **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
4. **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