Security & Compliance

Security is foundational to voicetyped. Organizations deploying voice automation in regulated industries need assurance that audio data, transcripts, and call records are protected. voicetyped provides defense-in-depth security controls that address common compliance requirements.

Security Architecture

External                         │ Internal
                                 │
  SIP Client ──── SIP-TLS ──────►│ Media Gateway
                                 │      │ (mTLS)
                                 │      ▼
                                 │ Speech Gateway
                                 │      │ (mTLS)
                                 │      ▼
                                 │ Runtime
                                 │      │ (mTLS)
                                 │      ▼
                                 │ Integration Gateway
                                 │      │ (mTLS)
                                 │      ▼
  Customer Backend ◄── mTLS ─────│

All inter-service communication uses mTLS (ConnectRPC over TLS). External connections support SIP-TLS and HTTPS.

mTLS Configuration

Enable mTLS

# /etc/voice-gateway/config.yaml

security:
  mtls:
    enabled: true
    cert_dir: /etc/voice-gateway/certs/

    # Server certificate (presented to clients)
    server_cert: /etc/voice-gateway/certs/server.pem
    server_key: /etc/voice-gateway/certs/server-key.pem

    # CA certificate (for verifying client certs)
    ca_cert: /etc/voice-gateway/certs/ca.pem

    # Client certificate (for outbound connections)
    client_cert: /etc/voice-gateway/certs/client.pem
    client_key: /etc/voice-gateway/certs/client-key.pem

    # Minimum TLS version
    min_version: "1.3"

    # Require client certificates
    client_auth: require

Generate Certificates

Using OpenSSL:

# Create CA
openssl req -x509 -newkey rsa:4096 -keyout ca-key.pem -out ca.pem \
  -days 3650 -nodes -subj "/CN=VoiceGateway CA"

# Create server certificate
openssl req -newkey rsa:4096 -keyout server-key.pem -out server.csr \
  -nodes -subj "/CN=voice-gateway.internal"
openssl x509 -req -in server.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out server.pem -days 365

# Create client certificate
openssl req -newkey rsa:4096 -keyout client-key.pem -out client.csr \
  -nodes -subj "/CN=vg-client"
openssl x509 -req -in client.csr -CA ca.pem -CAkey ca-key.pem \
  -CAcreateserial -out client.pem -days 365

Per-Client Certificates

Issue unique certificates for each integration client:

security:
  mtls:
    client_auth: require
    # Map client certificate CNs to roles
    client_roles:
      - cn: "admin-service"
        roles: [admin, read, write]
      - cn: "monitoring-service"
        roles: [read]
      - cn: "hook-service"
        roles: [hooks]

Encryption at Rest

Audio Data

By default, audio data is processed in-memory and never written to disk. If recording is enabled, recordings are encrypted:

security:
  encryption:
    at_rest:
      enabled: true
      algorithm: AES-256-GCM
      key_source: env               # env, file, vault
      key_env_var: VG_ENCRYPTION_KEY # For key_source: env

Transcript Storage

Transcripts are ephemeral by default (in-memory only). If persistence is configured:

security:
  encryption:
    transcripts:
      enabled: true
      algorithm: AES-256-GCM
      key_rotation_days: 90          # Rotate encryption keys

Audit Logging

Every significant action is logged to an audit trail:

security:
  audit:
    enabled: true
    output: file                     # file, syslog, stdout
    file_path: /var/log/voice-gateway/audit.log
    events:
      - call_started
      - call_terminated
      - transcript_generated
      - action_executed
      - hook_called
      - config_changed
      - auth_failure
    include_caller_id: true
    include_transcript: false        # Disable for privacy
    redact_fields:
      - ssn
      - credit_card
      - password

Audit Log Format

{
  "timestamp": "2024-01-15T10:30:45.123Z",
  "event": "call_started",
  "session_id": "abc-123-def",
  "caller_id": "+15551234567",
  "called_number": "+18001234567",
  "dialog": "helpdesk",
  "source_ip": "192.168.1.100",
  "user_agent": "Opal/1.0"
}

{
  "timestamp": "2024-01-15T10:31:12.456Z",
  "event": "hook_called",
  "session_id": "abc-123-def",
  "service": "ticketing",
  "method": "CreateTicket",
  "status": "OK",
  "duration_ms": 234
}

{
  "timestamp": "2024-01-15T10:32:00.789Z",
  "event": "call_terminated",
  "session_id": "abc-123-def",
  "duration_seconds": 76,
  "reason": "normal",
  "state_transitions": 5,
  "final_state": "goodbye"
}

Recording Controls

Audio recording is disabled by default. When enabled, it has strict controls:

security:
  recording:
    enabled: false                   # Disabled by default
    # When enabled:
    format: wav                      # wav, opus
    storage_dir: /var/lib/voice-gateway/recordings/
    encryption: true                 # Encrypt recordings at rest
    retention_days: 30               # Auto-delete after 30 days
    consent_prompt: true             # Play consent prompt before recording
    consent_text: "This call may be recorded for quality purposes."
    # Only record specific dialogs
    dialogs:
      - helpdesk
      - complaints

API Authentication

REST API

security:
  api:
    auth_method: mtls               # mtls, api_key, both
    # For API key auth:
    api_keys:
      - name: admin-key
        key_hash: "$2a$10$..."      # bcrypt hash
        roles: [admin]
      - name: read-only
        key_hash: "$2a$10$..."
        roles: [read]

API Key Usage

# Using API key with curl
curl -H "Authorization: Bearer YOUR_API_KEY" \
  http://localhost:8080/v1/calls

RBAC

Role-based access control for the API:

Role	Permissions
`admin`	Full access to all APIs
`read`	Read-only access (ListCalls, GetCall, SubscribeCalls)
`write`	Call control (PlayTTS, Hangup, Transfer)
`hooks`	Dialog hooks only (OnIntent, OnCallStart, OnCallEnd)

security:
  rbac:
    enabled: true
    roles:
      admin:
        - "*"
      read:
        - "VoiceGateway.ListCalls"
        - "VoiceGateway.GetCall"
        - "VoiceGateway.SubscribeCalls"
      write:
        - "CallControl.*"
      hooks:
        - "DialogHooks.*"

Network Security

Recommended Firewall Rules

# Allow SIP from known carriers only
iptables -A INPUT -p udp --dport 5060 -s 10.0.0.0/8 -j ACCEPT
iptables -A INPUT -p udp --dport 5060 -j DROP

# Allow RTP from SIP peers only
iptables -A INPUT -p udp --dport 10000:20000 -s 10.0.0.0/8 -j ACCEPT

# Allow REST API from internal network only
iptables -A INPUT -p tcp --dport 8080 -s 10.0.0.0/8 -j ACCEPT

# Allow metrics from monitoring network
iptables -A INPUT -p tcp --dport 9100 -s 10.1.0.0/16 -j ACCEPT

SIP Security

media:
  sip_tls:
    enabled: true
    cert: /etc/voice-gateway/certs/sip-server.pem
    key: /etc/voice-gateway/certs/sip-server-key.pem
  sip_allowed_ips:
    - 10.0.0.0/8
    - 172.16.0.0/12

Compliance Considerations

HIPAA

For healthcare deployments:

Enable mTLS on all connections
Disable recording or enable with encryption
Enable audit logging with include_transcript: false
Use air-gapped deployment
Implement access controls via RBAC

PCI-DSS

For payment processing:

Enable encryption at rest for all stored data
Enable audit logging
Redact credit card numbers from transcripts
Restrict network access to cardholder data environment

For European deployments:

Configure data retention policies
Enable audit logging for data access tracking
Support data deletion requests via API
Disable transcript storage or implement consent mechanisms

Security Checklist

Enable mTLS between all services
Use TLS 1.3 minimum
Issue per-client certificates
Enable audit logging
Configure log retention
Disable recording (or encrypt if required)
Set up RBAC
Configure firewall rules
Restrict SIP to known peers
Enable encryption at rest
Rotate certificates before expiry
Review audit logs regularly

Next Steps

Observability — monitoring and alerting
Kubernetes Deployment — network policies and pod security
Air-Gapped Deployment — classified environment setup