TrustPinError

Exception types for TrustPin SSL certificate pinning failures.

TrustPin provides detailed error information to help with debugging certificate pinning issues and implementing appropriate error handling strategies. Each error object 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

try {
    trustPin.verify("api.example.com", certificate)
} catch (e: TrustPinError.DomainNotRegistered) {
    // Handle unregistered domain (strict mode only)
    logger.warning("Unregistered domain accessed")
} catch (e: TrustPinError.PinsMismatch) {
    // Critical security issue - possible MITM attack
    logger.critical("Certificate pinning failed")
    throw SecurityException("Potential MITM attack detected")
} catch (e: TrustPinError.InvalidServerCert) {
    // Certificate format issue
    logger.error("Invalid certificate format")
} catch (e: TrustPinError.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

See also

Inheritors