Enumerations

Represents possible errors thrown by the TrustPin library.

TrustPin provides detailed error information to help with debugging certificate pinning issues and implementing appropriate error handling strategies. Each error case represents a specific failure scenario with distinct security implications.

Error Categories

• Configuration errors: Issues with setup parameters or credentials
• Network errors: Problems fetching pinning configurations
• Certificate errors: Invalid or malformed certificates
• Validation errors: Certificate doesn’t match configured pins
• Security errors: Potential security threats or policy violations

Example Error Handling

do {
    try await TrustPin.verify(domain: "api.example.com", certificate: cert)
} catch TrustPinErrors.domainNotRegistered {
    // Handle unregistered domain (strict mode only)
    logger.warning("Unregistered domain accessed")
} catch TrustPinErrors.pinsMismatch {
    // Critical security issue - possible MITM attack
    logger.critical("Certificate pinning failed")
    throw SecurityError.potentialMITMAttack
} catch TrustPinErrors.invalidServerCert {
    // Certificate format issue
    logger.error("Invalid certificate format")
} catch TrustPinErrors.errorFetchingPinningInfo {
    // Network connectivity issue
    logger.error("Unable to fetch pinning configuration")
}

Security Response Guidelines

• pinsMismatch: Treat as potential MITM attack, do not retry
• domainNotRegistered: Log for security monitoring, handle per mode
• allPinsExpired: Update pins urgently, consider emergency bypass
• invalidServerCert: Investigate certificate source and format
• errorFetchingPinningInfo: Retry with exponential backoff
• configurationValidationFailed: Check credentials and network integrity
• invalidProjectConfig: Verify credentials and configuration

Topics

Configuration Errors

• invalidProjectConfig

Network Errors

• errorFetchingPinningInfo
• configurationValidationFailed

Certificate Errors

• invalidServerCert

Validation Errors

• pinsMismatch
• allPinsExpired

Security Errors

• domainNotRegistered

See more

public enum TrustPinErrors : Error

extension TrustPinErrors: LocalizedError

Represents the severity level of a log message.

Used by the TrustPin logging infrastructure to control what types of messages are recorded or displayed.

See more

public enum TrustPinLogLevel : Int, Sendable

Defines the behavior for handling unregistered domains in TrustPin certificate pinning.

This enum controls how TrustPin behaves when attempting to verify certificates for domains that are not configured in your pinning configuration. The choice between modes affects both security posture and application flexibility.

Security Considerations

Choose your pinning mode based on your security requirements and application architecture:

• Production applications: Use strict mode to ensure all connections are validated
• Development/Testing: Use permissive mode to allow connections to test servers
• Hybrid applications: Use permissive mode when connecting to both controlled and uncontrolled services

Usage Examples

Strict Mode (Production)

try await TrustPin.setup(TrustPinConfiguration(
    organizationId: "prod-org-123",
    projectId: "mobile-app-v2",
    publicKey: "LS0tLS1CRUdJTi..."
    // mode defaults to .strict — recommended for production
))

Permissive Mode (Development)

try await TrustPin.setup(TrustPinConfiguration(
    organizationId: "dev-org-456",
    projectId: "mobile-app-staging",
    publicKey: "LS0tLS1CRUdJTk...",
    mode: .permissive  // Allows unregistered domains
))

Migration Strategy

When implementing certificate pinning in existing applications:

1. Phase 1: Deploy with permissive mode to identify all domains in use
2. Phase 2: Register critical domains in TrustPin dashboard
3. Phase 3: Switch to strict mode for production security

Topics

Pinning Modes

• strict
• permissive

See more

public enum TrustPinMode : Sendable