Security Architecture¶

Substation takes security seriously. This document outlines the security measures, architecture, and best practices implemented to protect your OpenStack credentials and data.

Executive Summary¶

AES-256-GCM encryption for all credentials (cross-platform)
Proper SSL/TLS certificate validation (no bypasses)
Comprehensive input validation (injection attack prevention)
Memory-safe credential handling with automatic zeroing
Zero plaintext credentials in memory or logs

Threat Model¶

Assets Protected¶

OpenStack Credentials
Username/password combinations
Application credential secrets
Authentication tokens
API keys
Configuration Data
clouds.yaml contents
Custom OpenStack endpoints
Project/tenant information
Session Data
Active authentication tokens
Cached resource data
API responses

Threat Actors¶

Network Attackers: Man-in-the-middle attacks, packet sniffing
Local Attackers: Memory dumps, process inspection, file access
Malicious Input: Injection attacks via user-provided data
System Compromise: Post-compromise credential extraction

Security Architecture¶

graph TB
    subgraph "Authentication"
        Creds[Credentials Manager]
        Token[Token Manager]
        Secure[SecureCredentialStorage]
    end

    subgraph "Data Protection"
        Encrypt[AES-256-GCM Encryption]
        SecString[SecureString/SecureBuffer]
        Memory[Memory Zeroing]
    end

    subgraph "Network Security"
        TLS[TLS 1.2+ Required]
        Cert[Certificate Validation]
        URLSec[URLSession Security]
    end

    subgraph "Input Protection"
        Validator[InputValidator]
        SQLCheck[SQL Injection Detection]
        CmdCheck[Command Injection Prevention]
        PathCheck[Path Traversal Protection]
    end

    User[User Request] --> Creds
    Creds --> Token
    Token --> Secure

    Secure --> Encrypt
    Encrypt --> SecString
    SecString --> Memory

    Token --> TLS
    TLS --> Cert
    Cert --> URLSec

    Input[User Input] --> Validator
    Validator --> SQLCheck
    Validator --> CmdCheck
    Validator --> PathCheck

1. Encryption¶

AES-256-GCM for Credential Storage¶

All sensitive credentials are encrypted using AES-256-GCM (Galois/Counter Mode), providing:

Confidentiality: 256-bit encryption strength
Authenticity: Built-in message authentication
Integrity: Tamper detection via authentication tags
Performance: Hardware-accelerated on modern CPUs

Implementation:

// CredentialEncryption class (OpenStackClientCore.swift)
public func encrypt(_ data: Data) throws -> Data {
    let symmetricKey = SymmetricKey(data: key)
    let sealedBox = try AES.GCM.seal(data, using: symmetricKey)
    return sealedBox.combined!
}

Key Features:

Cross-platform via Apple's swift-crypto library
Session-based encryption keys (256-bit random)
Automatic key generation using cryptographically-secure RNG
Keys never stored to disk

SecureString and SecureBuffer¶

Memory-safe wrappers for sensitive string data:

// SecureString (OpenStackClientCore.swift)
public struct SecureString: Sendable {
    private let buffer: SecureBuffer

    deinit {
        // Automatic memory zeroing
        buffer.clear()
    }
}

Features:

Automatic memory zeroing on deallocation
Limited lifetime in plaintext form
No string copies or interpolation
Prevents accidental logging

2. Certificate Validation¶

Apple Platforms (macOS)¶

Uses the Security framework for comprehensive validation:

let policy = SecPolicyCreateSSL(true, host as CFString)
SecTrustSetPolicies(serverTrust, policy)

var error: CFError?
let isValid = SecTrustEvaluateWithError(serverTrust, &error)

Validates:

Certificate chain integrity
Certificate expiration
Hostname matching
Trusted CA verification
Revocation status (OCSP/CRL)

Linux Platforms¶

Uses URLSession's built-in validation:

// Delegates to system CA bundle
completionHandler(.performDefaultHandling, nil)

Validates:

Certificate chain against system CA bundle
Certificate expiration
Hostname verification
Standard X.509 validation rules

3. Input Validation¶

InputValidator Utility¶

Centralized validation protects against:

SQL Injection (14 patterns detected):

UNION SELECT attacks
INSERT INTO / DELETE FROM / DROP TABLE
Comment-based injection (--, #)
Quote-based injection ('; DROP TABLE)

Command Injection (6 patterns detected):

Shell metacharacters (;, |, &, $)
Command substitution (`, $())
Redirection operators (>, <)

Path Traversal (3 patterns detected):

Directory traversal (../, ..\\)
URL-encoded traversal (%2e%2e/)
Mixed encoding attacks

Buffer Overflow Protection:

Configurable length limits (default 255 characters)
Enforced on all user input fields
Prevents memory exhaustion attacks

Example Usage¶

// Validate resource name
errors.append(contentsOf: InputValidator.validateNameField(name, maxLength: 255))

// Validate IP address
errors.append(contentsOf: InputValidator.validateIPAddress(ipAddress))

// Validate CIDR notation
errors.append(contentsOf: InputValidator.validateCIDR(cidr))

4. Secure Storage¶

SecureCredentialStorage Actor¶

Thread-safe encrypted credential storage:

public actor SecureCredentialStorage {
    private var credentials: [String: Data] = [:]  // AES-256-GCM encrypted
    private var encryptionKey: Data?

    deinit {
        // Secure cleanup - zero all memory
        for (_, var data) in credentials {
            data.withUnsafeMutableBytes { bytes in
                if let baseAddress = bytes.baseAddress {
                    memset(baseAddress, 0, bytes.count)
                }
            }
        }
        credentials.removeAll()
        encryptionKey = nil
    }
}

Features:

Actor-based concurrency (thread-safe)
AES-256-GCM encryption for all stored data
Automatic memory zeroing on deallocation
No disk persistence (memory-only)

5. Authentication Flow¶

Token Management¶

sequenceDiagram
    participant App as Application
    participant TM as CoreTokenManager
    participant Enc as CredentialEncryption
    participant OS as OpenStack API

    App->>TM: Request authenticated token
    TM->>TM: Check cached token validity
    alt Token Valid
        TM->>Enc: Decrypt token
        Enc-->>TM: Plaintext token
        TM-->>App: Return token
    else Token Expired/Missing
        TM->>OS: POST /auth/tokens
        OS-->>TM: Token + Expiry
        TM->>Enc: Encrypt token
        Enc-->>TM: Encrypted token
        TM->>TM: Cache encrypted token
        TM-->>App: Return token
    end
    Note over TM: Token auto-expires 5min before actual expiry

Security Features:

Tokens encrypted at rest (AES-256-GCM)
Automatic refresh before expiry
No disk storage of tokens
Memory cleared on process exit

Credential Flow¶

graph LR
    A[clouds.yaml] -->|Parse| B[AuthConfig]
    B -->|Load| C[SecureCredentialStorage]
    C -->|Encrypt| D[AES-256-GCM]
    D -->|Store| E[Memory Only]
    E -->|Decrypt| F[SecureString]
    F -->|Use| G[API Request]
    G -->|Clear| H[Zeroed Memory]

Security Best Practices¶

For Users¶

Protect clouds.yaml

chmod 600 ~/.config/openstack/clouds.yaml

Use Application Credentials
Prefer application credentials over passwords
Scope to specific projects
Set expiration dates
Keep Substation Updated
Security patches released promptly
Check GitHub releases regularly
Verify HTTPS Endpoints
Always use https:// in auth_url
Verify certificate warnings
Don't disable certificate validation

For Developers¶

Never Log Credentials

// WRONG
logger.logInfo("Password: \(password)")

// CORRECT
logger.logInfo("Authenticating user: \(username)")

Use SecureString for Passwords

// WRONG
var password: String

// CORRECT
let password = SecureString(rawPassword)
defer { password.clear() }

Validate All Input

// WRONG
func createServer(name: String) { ... }

// CORRECT
func createServer(name: String) throws {
    let errors = InputValidator.validateNameField(name)
    guard errors.isEmpty else { throw ValidationError(errors) }
    ...
}

Clear Sensitive Data

defer {
    sensitiveData.resetBytes(in: 0..<sensitiveData.count)
}

Cryptographic Details¶

Algorithms¶

Purpose	Algorithm	Key Size	Mode
Credential Encryption	AES	256-bit	GCM
Token Encryption	AES	256-bit	GCM
Random Generation	CSPRNG	256-bit	N/A
TLS/SSL	System	Varies	Default

Key Derivation¶

Session Keys:

Generated using cryptographically-secure RNG
256 bits of entropy
Unique per application instance
Never persisted to disk
Cleared on process exit

Platform-Specific:

macOS: SecRandomCopyBytes (Security framework)
Linux: arc4random_buf (libc)

Encryption Modes¶

AES-GCM Advantages:

Authenticated encryption (AEAD)
Detects tampering automatically
Single-pass operation (fast)
Hardware acceleration (AES-NI)
No padding oracle attacks

Security Hardening¶

Recommended System Configuration¶

File Permissions

chmod 700 ~/.config/openstack
chmod 600 ~/.config/openstack/clouds.yaml

Firewall Rules
Allow outbound HTTPS (443) to OpenStack endpoints
Block unnecessary inbound connections
Use VPN for untrusted networks
System Updates
Keep OS updated
Update swift-crypto when available
Monitor security advisories
Process Isolation
Run Substation as non-root user
Use separate user account if possible
Consider containerization for isolation

Security Monitoring¶

Logging¶

What is Logged:

Authentication attempts (username only)
API request failures
Certificate validation failures
Input validation failures

What is NOT Logged:

Passwords or credentials
Authentication tokens
Sensitive API responses
Full stack traces with data

Metrics¶

Security-relevant metrics tracked:

Authentication success/failure rate
Certificate validation failures
Input validation rejection rate
Memory usage patterns

Alerting¶

Automatic alerts for:

Repeated authentication failures
Certificate validation failures
Unusual memory usage patterns
API error rate spikes

Conclusion¶

Substation implements defense-in-depth security with multiple layers:

Encryption: AES-256-GCM for all credentials
Validation: Certificate and input validation
Isolation: Memory safety and secure cleanup
Monitoring: Security event tracking

Result: Your OpenStack credentials are protected against common attack vectors, with ongoing security improvements planned for future releases.

Security Architecture¶

Executive Summary¶

Threat Model¶

Assets Protected¶

Threat Actors¶

Security Architecture¶

1. Encryption¶

AES-256-GCM for Credential Storage¶

SecureString and SecureBuffer¶

2. Certificate Validation¶

Apple Platforms (macOS)¶

Linux Platforms¶

3. Input Validation¶

InputValidator Utility¶

Example Usage¶

4. Secure Storage¶

SecureCredentialStorage Actor¶

5. Authentication Flow¶

Token Management¶

Credential Flow¶

Security Best Practices¶

For Users¶

For Developers¶

Cryptographic Details¶

Algorithms¶

Key Derivation¶

Encryption Modes¶

Security Hardening¶

Recommended System Configuration¶

Network Security¶

Security Monitoring¶

Logging¶

Metrics¶

Alerting¶

Conclusion¶