# Payment Switch Integration Guide for SoftHSM

## Overview

This guide provides comprehensive instructions for integrating payment switch systems with the SoftHSM Payment Gateway. The SoftHSM provides hardware security module (HSM) capabilities for payment processing, including PIN block translation, key management, and cryptographic operations.

**⚠️ IMPORTANT SECURITY NOTICE**
This SoftHSM implementation is designed for development and testing environments. For production use, ensure proper security hardening and consider hardware HSM integration.

## Table of Contents

1. [System Architecture](#system-architecture)
2. [Authentication & Security](#authentication--security)
3. [API Endpoints Reference](#api-endpoints-reference)
4. [Payment Operations](#payment-operations)
5. [Key Management](#key-management)
6. [Error Handling](#error-handling)
7. [Integration Examples](#integration-examples)
8. [Testing Procedures](#testing-procedures)
9. [Production Considerations](#production-considerations)

## System Architecture

### Component Overview

```
┌─────────────────┐    HTTP/JSON     ┌─────────────────┐
│  Payment Switch │ ◄──────────────► │   SoftHSM API   │
│                 │                  │                 │
│ - Transaction   │                  │ - PIN Translation│
│   Processing    │                  │ - Key Management │
│ - Routing       │                  │ - Cryptographic  │
│ - Authorization │                  │   Operations     │
└─────────────────┘                  └─────────────────┘
                                              │
                                              ▼
                                     ┌─────────────────┐
                                     │  Key Database   │
                                     │                 │
                                     │ - TMK Storage   │
                                     │ - Working Keys  │
                                     │ - Audit Logs    │
                                     └─────────────────┘
```

### Key Hierarchy Model

```
LMK (Local Master Key)
 └── ZMK (Zone Master Key)
     └── TMK (Terminal Master Key)
         ├── PIK (PIN Encryption Key)
         ├── TEK (Terminal Encryption Key)
         └── MAK (Message Authentication Key)
```

## Authentication & Security

### Base URL
```
Production: https://your-domain.com/api/v1
Development: http://localhost:14000/api/v1
```

### Request Headers
```http
Content-Type: application/json
Authorization: Bearer <your-api-token>  # Future implementation
Accept: application/json
```

### Security Requirements

1. **TLS Encryption**: All API calls must use HTTPS in production
2. **API Authentication**: Implement proper API key management
3. **Request Signing**: Consider implementing request signing for critical operations
4. **IP Whitelisting**: Restrict access to known switch IP addresses
5. **Rate Limiting**: Implement appropriate rate limiting for your environment

## API Endpoints Reference

### Core HSM Operations

#### 1. Key Generation
```http
POST /hsm/generate
```

**Request Body:**
```json
{
  "key_type": "TMK",
  "length": 168,
  "usage": ["derive", "enc"],
  "exportable": false,
  "key_id": "TMK_TERM_001",
  "created_by": "switch_system"
}
```

**Response:**
```json
{
  "key_id": "TMK_TERM_001",
  "key_type": "TMK",
  "kcv": "A1B2C3",
  "status": "active",
  "created_at": "2025-10-21T10:30:00Z"
}
```

#### 2. Key Import
```http
POST /hsm/import
```

**Request Body:**
```json
{
  "key_id": "TMK_BANK_001",
  "wrapped_key": "A1B2C3D4E5F6789012345678",
  "wrapping_algo": "AES-KW",
  "wrapping_key_id": "KEK_001",
  "usage": ["derive", "enc"]
}
```

### Payment Operations

#### 1. PIN Block Translation
```http
POST /hsm/pin-block/translate
```

**Use Case**: Translate PIN block from acquirer's PEK to issuer's PEK

**Request Body:**
```json
{
  "pin_block": "1234567890ABCDEF",
  "source_pek_id": "PIK_ACQ_001_1", 
  "target_pek_id": "PIK_ISS_001_1",
  "pan": "4111111111111111"
}
```

**Response:**
```json
{
  "translated_pin_block": "FEDCBA0987654321",
  "format": "ISO_FORMAT_0",
  "kcv_source": "A1B2C3",
  "kcv_target": "D4E5F6",
  "timestamp": "2025-10-21T10:30:00Z"
}
```

#### 2. PIN Verification
```http
POST /hsm/pin-block/verify
```

**Use Case**: Verify customer PIN against encrypted PIN block

**Request Body:**
```json
{
  "pin_block": "1234567890ABCDEF",
  "pin": "1234",
  "pek_id": "PIK_TERM_001_1",
  "pan": "4111111111111111"
}
```

**Response:**
```json
{
  "valid": true,
  "format": "ISO_FORMAT_0",
  "verification_timestamp": "2025-10-21T10:30:00Z"
}
```

### Key Management Operations

#### 1. Derive Working Key
```http
POST /hsm/tmk/derive
```

**Use Case**: Derive PIN encryption key from terminal master key

**Request Body:**
```json
{
  "tmk_key_id": "TMK_TERM_001",
  "key_type": "PIK",
  "key_index": 1
}
```

**Response:**
```json
{
  "key_id": "PIK_TERM_001_1",
  "key_type": "PIK", 
  "parent_key_id": "TMK_TERM_001",
  "key_index": 1,
  "kcv": "789ABC",
  "pin_block_formats": ["FORMAT_0"],
  "status": "active",
  "derived_at": "2025-10-21T10:30:00Z"
}
```

#### 2. Get Working Key
```http
GET /hsm/working-key/{tmk_key_id}/{key_index}
```

**Example:**
```http
GET /hsm/working-key/TMK_TERM_001/1
```

**Response:**
```json
{
  "key_id": "PIK_TERM_001_1",
  "key_type": "PIK",
  "parent_key_id": "TMK_TERM_001", 
  "key_index": 1,
  "kcv": "789ABC",
  "status": "active"
}
```

#### 3. List Working Keys
```http
GET /hsm/working-keys/{tmk_key_id}
```

**Example:**
```http
GET /hsm/working-keys/TMK_TERM_001
```

**Response:**
```json
[
  {
    "key_id": "PIK_TERM_001_1",
    "key_type": "PIK",
    "key_index": 1,
    "kcv": "789ABC",
    "status": "active"
  },
  {
    "key_id": "TEK_TERM_001_2", 
    "key_type": "TEK",
    "key_index": 2,
    "kcv": "DEF123",
    "status": "active"
  }
]
```

### Cryptographic Operations

#### 1. Data Encryption
```http
POST /hsm/encrypt
```

**Request Body:**
```json
{
  "key_id": "TEK_TERM_001_2",
  "algorithm": "3DES_ECB",
  "data": "SGVsbG8gV29ybGQ="
}
```

#### 2. Data Decryption
```http
POST /hsm/decrypt
```

**Request Body:**
```json
{
  "key_id": "TEK_TERM_001_2",
  "algorithm": "3DES_ECB", 
  "data": "encrypted_base64_data"
}
```

#### 3. MAC Generation
```http
POST /hsm/mac
```

**Request Body:**
```json
{
  "key_id": "MAK_TERM_001_3",
  "algorithm": "3DES_MAC",
  "data": "message_to_authenticate"
}
```

## Payment Operations

### PIN Block Translation Workflow

```mermaid
sequenceDiagram
    participant Switch as Payment Switch
    participant HSM as SoftHSM API
    participant DB as Key Database

    Switch->>HSM: POST /hsm/pin-block/translate
    Note over Switch,HSM: pin_block, source_pek_id, target_pek_id, pan
    
    HSM->>DB: Load source PEK
    DB-->>HSM: Source PEK material
    
    HSM->>DB: Load target PEK  
    DB-->>HSM: Target PEK material
    
    HSM->>HSM: Decrypt with source PEK
    HSM->>HSM: Re-encrypt with target PEK
    
    HSM-->>Switch: Translated PIN block
    Note over Switch,HSM: translated_pin_block, kcv_source, kcv_target
```

### Key Derivation Workflow

```mermaid
sequenceDiagram
    participant Switch as Payment Switch
    participant HSM as SoftHSM API
    participant DB as Key Database

    Switch->>HSM: POST /hsm/tmk/derive
    Note over Switch,HSM: tmk_key_id, key_type, key_index
    
    HSM->>DB: Load TMK
    DB-->>HSM: TMK material
    
    HSM->>HSM: Derive working key using 3DES-ECB
    HSM->>HSM: Compute KCV
    
    HSM->>DB: Store derived key
    DB-->>HSM: Storage confirmation
    
    HSM-->>Switch: Working key metadata
    Note over Switch,HSM: key_id, kcv, status
```

## Error Handling

### HTTP Status Codes

| Code | Description | Usage |
|------|-------------|--------|
| 200 | OK | Successful operation |
| 201 | Created | Key generated/derived successfully |
| 400 | Bad Request | Invalid parameters or request format |
| 401 | Unauthorized | Authentication required |
| 403 | Forbidden | Access denied |
| 404 | Not Found | Key or resource not found |
| 500 | Internal Server Error | HSM or system error |

### Error Response Format

```json
{
  "error": "PIN block translation failed",
  "error_code": "TRANSLATION_ERROR",
  "details": [
    "Source PEK not found: PIK_ACQ_001_1"
  ],
  "timestamp": "2025-10-21T10:30:00Z",
  "request_id": "req_123456789"
}
```

### Common Error Scenarios

#### Key Not Found
```json
{
  "error": "Key not found",
  "error_code": "KEY_NOT_FOUND",
  "details": ["Key ID 'TMK_TERM_001' does not exist"],
  "timestamp": "2025-10-21T10:30:00Z"
}
```

#### Invalid PIN Block Format
```json
{
  "error": "Validation failed",
  "error_code": "VALIDATION_ERROR", 
  "details": ["pin_block must be 16 hex characters"],
  "timestamp": "2025-10-21T10:30:00Z"
}
```

#### Key Hierarchy Violation
```json
{
  "error": "Working key derivation failed",
  "error_code": "DERIVATION_ERROR",
  "details": ["TMK is not active or accessible"],
  "timestamp": "2025-10-21T10:30:00Z"
}
```

## Integration Examples

### Example 1: Terminal PIN Verification Flow

```python
import requests
import json

class PaymentHSMClient:
    def __init__(self, base_url, api_key=None):
        self.base_url = base_url
        self.headers = {
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        }
        if api_key:
            self.headers['Authorization'] = f'Bearer {api_key}'
    
    def setup_terminal_keys(self, terminal_id):
        """Setup keys for a new terminal"""
        # 1. Generate TMK for terminal
        tmk_response = requests.post(
            f"{self.base_url}/hsm/generate",
            headers=self.headers,
            json={
                "key_type": "TMK",
                "length": 168,
                "usage": ["derive", "enc"],
                "exportable": False,
                "key_id": f"TMK_TERM_{terminal_id}",
                "created_by": "payment_switch"
            }
        )
        
        if tmk_response.status_code != 201:
            raise Exception(f"TMK generation failed: {tmk_response.text}")
        
        tmk_data = tmk_response.json()
        tmk_key_id = tmk_data['key_id']
        
        # 2. Derive PIK for PIN operations
        pik_response = requests.post(
            f"{self.base_url}/hsm/tmk/derive",
            headers=self.headers,
            json={
                "tmk_key_id": tmk_key_id,
                "key_type": "PIK",
                "key_index": 1
            }
        )
        
        if pik_response.status_code != 201:
            raise Exception(f"PIK derivation failed: {pik_response.text}")
        
        pik_data = pik_response.json()
        
        return {
            "terminal_id": terminal_id,
            "tmk": tmk_data,
            "pik": pik_data
        }
    
    def verify_pin(self, pin_block, pin, pek_id, pan):
        """Verify customer PIN"""
        response = requests.post(
            f"{self.base_url}/hsm/pin-block/verify",
            headers=self.headers,
            json={
                "pin_block": pin_block,
                "pin": pin,
                "pek_id": pek_id,
                "pan": pan
            }
        )
        
        if response.status_code == 200:
            return response.json()['valid']
        else:
            raise Exception(f"PIN verification failed: {response.text}")
    
    def translate_pin_block(self, pin_block, source_pek, target_pek, pan):
        """Translate PIN block between different PEKs"""
        response = requests.post(
            f"{self.base_url}/hsm/pin-block/translate",
            headers=self.headers,
            json={
                "pin_block": pin_block,
                "source_pek_id": source_pek,
                "target_pek_id": target_pek,
                "pan": pan
            }
        )
        
        if response.status_code == 200:
            return response.json()['translated_pin_block']
        else:
            raise Exception(f"PIN translation failed: {response.text}")

# Usage Example
hsm_client = PaymentHSMClient("http://localhost:14000/api/v1")

# Setup keys for terminal
terminal_keys = hsm_client.setup_terminal_keys("001")
print(f"Terminal setup complete:")
print(f"TMK: {terminal_keys['tmk']['key_id']} (KCV: {terminal_keys['tmk']['kcv']})")
print(f"PIK: {terminal_keys['pik']['key_id']} (KCV: {terminal_keys['pik']['kcv']})")

# Verify PIN
is_valid = hsm_client.verify_pin(
    pin_block="1234567890ABCDEF",
    pin="1234", 
    pek_id=terminal_keys['pik']['key_id'],
    pan="4111111111111111"
)
print(f"PIN verification result: {is_valid}")
```

### Example 2: Switch-to-Switch PIN Translation

```javascript
const axios = require('axios');

class HSMClient {
    constructor(baseUrl, apiKey = null) {
        this.baseUrl = baseUrl;
        this.headers = {
            'Content-Type': 'application/json',
            'Accept': 'application/json'
        };
        if (apiKey) {
            this.headers['Authorization'] = `Bearer ${apiKey}`;
        }
    }

    async translatePinBlock(pinBlock, sourcePekId, targetPekId, pan) {
        try {
            const response = await axios.post(
                `${this.baseUrl}/hsm/pin-block/translate`,
                {
                    pin_block: pinBlock,
                    source_pek_id: sourcePekId,
                    target_pek_id: targetPekId,
                    pan: pan
                },
                { headers: this.headers }
            );
            
            return response.data;
        } catch (error) {
            throw new Error(`PIN translation failed: ${error.response?.data?.error || error.message}`);
        }
    }

    async processTransaction(transaction) {
        const {
            pinBlock,
            pan,
            acquirerPekId,
            issuerPekId
        } = transaction;

        // Translate PIN block from acquirer to issuer format
        const translationResult = await this.translatePinBlock(
            pinBlock,
            acquirerPekId,
            issuerPekId,
            pan
        );

        return {
            original_pin_block: pinBlock,
            translated_pin_block: translationResult.translated_pin_block,
            source_kcv: translationResult.kcv_source,
            target_kcv: translationResult.kcv_target,
            translation_timestamp: translationResult.timestamp
        };
    }
}

// Usage
const hsmClient = new HSMClient('http://localhost:14000/api/v1');

// Process transaction with PIN translation
const transaction = {
    pinBlock: '1234567890ABCDEF',
    pan: '4111111111111111',
    acquirerPekId: 'PIK_ACQ_001_1',
    issuerPekId: 'PIK_ISS_001_1'
};

hsmClient.processTransaction(transaction)
    .then(result => {
        console.log('Transaction processed:', result);
    })
    .catch(error => {
        console.error('Transaction failed:', error.message);
    });
```

### Example 3: Java Integration

```java
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.JsonNode;

public class HSMClient {
    private final String baseUrl;
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    private final String apiKey;

    public HSMClient(String baseUrl, String apiKey) {
        this.baseUrl = baseUrl;
        this.apiKey = apiKey;
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }

    public String translatePinBlock(String pinBlock, String sourcePekId, 
                                   String targetPekId, String pan) throws Exception {
        
        String requestBody = objectMapper.writeValueAsString(Map.of(
            "pin_block", pinBlock,
            "source_pek_id", sourcePekId,
            "target_pek_id", targetPekId,
            "pan", pan
        ));

        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/hsm/pin-block/translate"))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody));

        if (apiKey != null) {
            requestBuilder.header("Authorization", "Bearer " + apiKey);
        }

        HttpRequest request = requestBuilder.build();
        HttpResponse<String> response = httpClient.send(request, 
                                                       HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 200) {
            JsonNode jsonResponse = objectMapper.readTree(response.body());
            return jsonResponse.get("translated_pin_block").asText();
        } else {
            throw new RuntimeException("PIN translation failed: " + response.body());
        }
    }

    public boolean verifyPin(String pinBlock, String pin, String pekId, String pan) throws Exception {
        String requestBody = objectMapper.writeValueAsString(Map.of(
            "pin_block", pinBlock,
            "pin", pin,
            "pek_id", pekId,
            "pan", pan
        ));

        HttpRequest.Builder requestBuilder = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/hsm/pin-block/verify"))
            .header("Content-Type", "application/json")
            .header("Accept", "application/json")
            .POST(HttpRequest.BodyPublishers.ofString(requestBody));

        if (apiKey != null) {
            requestBuilder.header("Authorization", "Bearer " + apiKey);
        }

        HttpRequest request = requestBuilder.build();
        HttpResponse<String> response = httpClient.send(request, 
                                                       HttpResponse.BodyHandlers.ofString());

        if (response.statusCode() == 200) {
            JsonNode jsonResponse = objectMapper.readTree(response.body());
            return jsonResponse.get("valid").asBoolean();
        } else {
            throw new RuntimeException("PIN verification failed: " + response.body());
        }
    }
}

// Usage Example
public class PaymentProcessor {
    public static void main(String[] args) {
        HSMClient hsmClient = new HSMClient("http://localhost:14000/api/v1", null);
        
        try {
            // Verify PIN
            boolean isValid = hsmClient.verifyPin(
                "1234567890ABCDEF",
                "1234",
                "PIK_TERM_001_1",
                "4111111111111111"
            );
            System.out.println("PIN verification result: " + isValid);

            // Translate PIN block
            String translatedPinBlock = hsmClient.translatePinBlock(
                "1234567890ABCDEF",
                "PIK_ACQ_001_1",
                "PIK_ISS_001_1", 
                "4111111111111111"
            );
            System.out.println("Translated PIN block: " + translatedPinBlock);
            
        } catch (Exception e) {
            System.err.println("HSM operation failed: " + e.getMessage());
        }
    }
}
```

## Testing Procedures

### Unit Testing

#### 1. Key Generation Test
```bash
curl -X POST http://localhost:14000/api/v1/hsm/generate \
  -H "Content-Type: application/json" \
  -d '{
    "key_type": "TMK",
    "length": 168,
    "usage": ["derive", "enc"],
    "exportable": false,
    "key_id": "TMK_TEST_001"
  }'
```

Expected Response:
```json
{
  "key_id": "TMK_TEST_001",
  "key_type": "TMK",
  "kcv": "A1B2C3",
  "status": "active"
}
```

#### 2. Working Key Derivation Test
```bash
curl -X POST http://localhost:14000/api/v1/hsm/tmk/derive \
  -H "Content-Type: application/json" \
  -d '{
    "tmk_key_id": "TMK_TEST_001",
    "key_type": "PIK",
    "key_index": 1
  }'
```

#### 3. PIN Block Translation Test
```bash
curl -X POST http://localhost:14000/api/v1/hsm/pin-block/translate \
  -H "Content-Type: application/json" \
  -d '{
    "pin_block": "1234567890ABCDEF",
    "source_pek_id": "PIK_TEST_001_1",
    "target_pek_id": "PIK_TEST_002_1",
    "pan": "4111111111111111"
  }'
```

### Integration Testing

#### Test Scenario 1: Full Payment Flow
1. Generate TMK for terminal
2. Derive PIK from TMK
3. Generate test PIN block
4. Verify PIN against PIN block
5. Translate PIN block to different PEK
6. Verify translated PIN block

#### Test Scenario 2: Error Handling
1. Test with invalid key IDs
2. Test with malformed PIN blocks
3. Test with invalid PAN formats
4. Test rate limiting behavior
5. Test concurrent access

#### Test Scenario 3: Performance Testing
1. Measure PIN translation latency
2. Test concurrent PIN verifications
3. Measure key derivation performance
4. Test system under load

### Test Data Sets

#### Valid Test Cases
```json
{
  "test_cases": [
    {
      "name": "Standard PIN verification",
      "pin": "1234",
      "pan": "4111111111111111",
      "expected_pin_block": "041234EEEEEEEEEE"
    },
    {
      "name": "Long PIN verification", 
      "pin": "123456",
      "pan": "4111111111111111",
      "expected_pin_block": "0612345EEEEEEEEE"
    },
    {
      "name": "Different PAN",
      "pin": "9876",
      "pan": "5555444433332222",
      "expected_pin_block": "049876DDDDDDCCCC"
    }
  ]
}
```

## Production Considerations

### Security Hardening

#### 1. Hardware HSM Integration
- Replace software HSM with certified hardware HSM
- Implement proper key injection procedures
- Use hardware-backed key storage
- Enable HSM clustering for high availability

#### 2. Network Security
```nginx
# Example Nginx configuration for HSM API proxy
upstream hsm_backend {
    server 127.0.0.1:14000;
    keepalive 32;
}

server {
    listen 443 ssl http2;
    server_name hsm-api.your-domain.com;
    
    ssl_certificate /path/to/certificate.crt;
    ssl_certificate_key /path/to/private.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;
    
    # Rate limiting
    limit_req_zone $binary_remote_addr zone=hsm_api:10m rate=100r/m;
    limit_req zone=hsm_api burst=20 nodelay;
    
    # IP whitelisting
    allow 10.0.0.0/8;
    allow 192.168.0.0/16;
    deny all;
    
    location /api/v1/hsm/ {
        proxy_pass http://hsm_backend;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        
        # Timeout settings
        proxy_connect_timeout 5s;
        proxy_send_timeout 10s;
        proxy_read_timeout 10s;
    }
}
```

#### 3. Authentication & Authorization
```python
# Example API authentication middleware
import jwt
import time
from functools import wraps

def require_auth(f):
    @wraps(f)
    def decorated_function(*args, **kwargs):
        token = request.headers.get('Authorization')
        if not token:
            return jsonify({'error': 'No token provided'}), 401
        
        try:
            token = token.replace('Bearer ', '')
            payload = jwt.decode(token, SECRET_KEY, algorithms=['HS256'])
            
            # Check token expiration
            if payload['exp'] < time.time():
                return jsonify({'error': 'Token expired'}), 401
                
            # Check permissions
            if 'hsm:operation' not in payload.get('permissions', []):
                return jsonify({'error': 'Insufficient permissions'}), 403
                
        except jwt.InvalidTokenError:
            return jsonify({'error': 'Invalid token'}), 401
        
        return f(*args, **kwargs)
    return decorated_function
```

### Monitoring & Alerting

#### 1. Key Metrics to Monitor
- PIN translation success rate
- Average response time
- Key derivation rate
- Error rate by operation type
- HSM availability
- Database connection health

#### 2. Alert Conditions
```yaml
# Example monitoring configuration
alerts:
  - name: "HSM High Error Rate"
    condition: "error_rate > 5%"
    duration: "5m"
    severity: "critical"
    
  - name: "PIN Translation Latency"
    condition: "avg_latency > 500ms"
    duration: "2m"
    severity: "warning"
    
  - name: "Key Derivation Failure"
    condition: "derivation_errors > 0"
    duration: "1m"
    severity: "critical"
    
  - name: "Database Connection Issues"
    condition: "db_connection_errors > 0"
    duration: "30s"
    severity: "critical"
```

#### 3. Audit Logging
```sql
-- Example audit query for compliance reporting
SELECT 
    operation,
    COUNT(*) as operation_count,
    COUNT(CASE WHEN result = 'success' THEN 1 END) as success_count,
    COUNT(CASE WHEN result = 'failure' THEN 1 END) as failure_count,
    AVG(CASE WHEN result = 'success' THEN 1.0 ELSE 0.0 END) * 100 as success_rate
FROM hsm_audit_logs 
WHERE inserted_at >= DATE_SUB(NOW(), INTERVAL 24 HOUR)
    AND operation IN ('translate_pin_block', 'verify_pin_block', 'derive_working_key')
GROUP BY operation
ORDER BY operation_count DESC;
```

### Performance Optimization

#### 1. Connection Pooling
```elixir
# Database connection pool configuration
config :da_product_app, DaProductApp.Repo,
  pool_size: 20,
  timeout: 15_000,
  ownership_timeout: 30_000,
  queue_target: 200,
  queue_interval: 5_000
```

#### 2. Caching Strategy
```elixir
# Key metadata caching
defmodule KeyCache do
  use GenServer
  
  def get_key_metadata(key_id) do
    case :ets.lookup(:key_cache, key_id) do
      [{^key_id, metadata, timestamp}] ->
        if System.system_time(:second) - timestamp < 300 do
          {:ok, metadata}
        else
          load_and_cache_key(key_id)
        end
      [] ->
        load_and_cache_key(key_id)
    end
  end
  
  defp load_and_cache_key(key_id) do
    case KeyStore.get_key_metadata(key_id) do
      {:ok, metadata} ->
        :ets.insert(:key_cache, {key_id, metadata, System.system_time(:second)})
        {:ok, metadata}
      error ->
        error
    end
  end
end
```

### Compliance Requirements

#### 1. PCI DSS Compliance Checklist
- [ ] Implement strong access controls
- [ ] Use strong cryptography for key protection
- [ ] Maintain audit logs for all HSM operations
- [ ] Implement network segmentation
- [ ] Regular penetration testing
- [ ] Vulnerability management program
- [ ] Secure key injection procedures
- [ ] Physical security controls

#### 2. Common Criteria Certification
- [ ] Use certified HSM hardware
- [ ] Implement proper key lifecycle management
- [ ] Document security policies and procedures
- [ ] Regular security assessments
- [ ] Personnel security controls

## Support & Troubleshooting

### Common Issues

#### Issue 1: Key Not Found Errors
**Symptoms**: 404 errors when accessing keys
**Causes**: 
- Key ID doesn't exist in database
- Key has been soft-deleted
- Database connection issues

**Resolution**:
1. Verify key exists: `GET /hsm/keys/{key_id}`
2. Check audit logs for key deletion events
3. Verify database connectivity

#### Issue 2: PIN Translation Failures
**Symptoms**: Translation returns errors or invalid results
**Causes**:
- Source or target PEK not accessible
- Invalid PIN block format
- Key material corruption

**Resolution**:
1. Verify both PEKs exist and are active
2. Validate PIN block format (16 hex characters)
3. Check KCV values for key integrity

#### Issue 3: Performance Issues
**Symptoms**: High latency, timeouts
**Causes**:
- Database connection pool exhaustion
- High concurrent load
- Network latency

**Resolution**:
1. Monitor connection pool metrics
2. Implement request queuing
3. Scale HSM instances horizontally

### Debug Mode

Enable debug logging for troubleshooting:

```bash
# Set log level to debug
export LOG_LEVEL=debug

# Enable HSM operation tracing
export HSM_TRACE=true

# Start server with debug mode
mix phx.server
```

### Contact Information

For technical support:
- **Email**: support@your-company.com
- **Slack**: #payment-systems-support
- **Documentation**: https://docs.your-company.com/hsm
- **Status Page**: https://status.your-company.com

---

**Document Version**: 1.0  
**Last Updated**: October 21, 2025  
**Next Review**: November 21, 2025