TrustPinErrors

The project configuration is invalid or incomplete.

This error occurs when the setup parameters provided to setup(_:autoRegisterURLProtocol:) are invalid, missing, or incorrectly formatted.

Common Causes

• Empty or whitespace-only organization ID, project ID, or public key
• Invalid base64 encoding in the public key
• Incorrect credential format or structure
• Network connectivity issues during credential validation

Resolution Steps

1. Verify credentials: Check organization ID and project ID in TrustPin dashboard
2. Validate public key: Ensure proper base64 encoding without extra characters
3. Check formatting: Remove any whitespace, newlines, or special characters
4. Test connectivity: Verify network access to TrustPin service

Example

do {
    let config = TrustPinConfiguration(
        organizationId: "org-123",
        projectId: "project-456",
        publicKey: "LS0tLS1CRUdJTi..."
    )
    try await TrustPin.setup(config)
} catch TrustPinErrors.invalidProjectConfig {
    print("Invalid credentials - check TrustPin dashboard")
}

Failed to fetch or parse the pinning configuration after exhausting all sources.

TrustPin attempts to download the JWS configuration from a prioritised chain of sources:

1. Custom configurationURL (if set)
2. TrustPin CDNs

The full chain is attempted twice. If all attempts fail and no valid stale cache is available, this error is thrown.

Common Causes

• Network connectivity issues affecting all CDN endpoints
• DNS resolution failures
• Firewall or proxy blocking HTTPS requests to TrustPin CDNs
• Simultaneous service downtime across all CDNs
• Invalid response format from all servers

Resolution Steps

1. Check connectivity: Verify internet connection and DNS resolution
2. Review firewall: Ensure HTTPS traffic to all TrustPin CDN hostnames is allowed
3. Check service status: Verify TrustPin service availability
4. Inspect logs: Enable .debug log level to see which CDN failed and why

The server certificate is invalid, corrupted, or could not be parsed.

This error occurs when the certificate provided to verify(domain:certificate:) is malformed, corrupted, or not in the expected PEM format.

Common Causes

• Invalid PEM format (missing BEGIN/END markers)
• Corrupted certificate data
• Incorrect encoding (not base64)
• Truncated or incomplete certificate
• Wrong certificate type (not X.509)

Certificate Format Requirements

Certificates must be in PEM format with proper markers:

-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END CERTIFICATE-----

Resolution Steps

1. Verify format: Ensure certificate includes BEGIN/END markers
2. Check encoding: Validate base64 encoding within markers
3. Test parsing: Use OpenSSL or similar tool to validate certificate
4. Source validation: Verify certificate source and extraction method

Example

do {
    try await TrustPin.verify(domain: "api.example.com", certificate: pemCert)
} catch TrustPinErrors.invalidServerCert {
    print("Certificate format is invalid - check PEM encoding")
}

No matching pins were found for the provided certificate.

This error occurs when the certificate’s public key hash doesn’t match any of the configured pins for the domain. This is a critical security error that may indicate a man-in-the-middle (MITM) attack or certificate rotation without pin updates.

Security Implications

• High severity: Potential security threat detected
• MITM attack: Certificate may be compromised or intercepted
• Service disruption: Legitimate certificate rotation without pin updates
• Configuration drift: Pins may be outdated or incorrect

Immediate Actions

1. Do not retry: This is not a transient error
2. Log security event: Record details for security monitoring
3. Alert administrators: Notify security team of potential threat
4. Block connection: Prevent potentially compromised connection

Investigation Steps

1. Verify certificate: Check if server certificate changed legitimately
2. Update pins: If legitimate change, update pins in TrustPin dashboard
3. Check network: Investigate for network-level interference
4. Review logs: Look for patterns indicating broader compromise

Example Handling

do {
    try await TrustPin.verify(domain: "api.example.com", certificate: cert)
} catch TrustPinErrors.pinsMismatch {
    // Critical security issue - do not retry
    logger.critical("Certificate pinning failed for \(domain)")
    securityMonitor.alert("Potential MITM attack detected")
    throw SecurityError.potentialMITMAttack
}

All configured pins for the domain have expired.

This error occurs when all the certificate pins configured for a domain have passed their expiration date. This indicates a maintenance issue that requires immediate attention to restore service availability.

Common Causes

• Expired certificates that weren’t renewed in time
• Outdated pin configuration in TrustPin dashboard
• Certificate rotation without pin updates
• Maintenance oversight or process failure

Immediate Actions

1. Check certificate validity: Verify if server certificate is still valid
2. Update pins: Generate new pins for current certificates
3. Emergency bypass: Consider temporary permissive mode if critical
4. Notify administrators: Alert operations team of expiration

Resolution Steps

1. TrustPin dashboard: Update expired pins with current certificate hashes
2. Certificate renewal: Renew certificates if they’re also expired
3. Process review: Improve pin management and renewal processes
4. Monitoring: Set up alerts for upcoming pin expirations

Emergency Bypass

If immediate service restoration is critical:

// Temporary permissive mode for emergency access
try await TrustPin.setup(TrustPinConfiguration(
    organizationId: orgId,
    projectId: projectId,
    publicKey: publicKey,
    mode: .permissive  // Temporary bypass
))

Prevention

• Monitoring: Set up alerts 30 days before pin expiration
• Automation: Implement automated pin renewal processes
• Staging testing: Test pin updates in staging environment first

• Documentation: Maintain clear pin management procedures

The payload failed validation (e.g., signature mismatch or invalid structure).

This error occurs when the validation fails for the downloaded pinning configuration. This indicates either a security issue or a configuration problem with the credentials.

Common Causes

• Credential mismatch: Public key doesn’t match the signature
• Corrupted payload: Network issues corrupted the downloaded configuration
• Tampering: Potential man-in-the-middle attack on configuration
• Service issues: Problems with TrustPin service signing
• Clock skew: Timestamp validation failures due to incorrect system time

Security Implications

• High severity: Configuration integrity compromised
• Potential attack: Configuration may have been tampered with
• Service disruption: Cannot proceed with pinning validation
• Trust breakdown: Fundamental security validation failed

Resolution Steps

1. Verify credentials: Ensure public key matches TrustPin dashboard
2. Check system time: Verify device clock is accurate
3. Test connectivity: Ensure clean network path to TrustPin service
4. Retry operation: Attempt fresh configuration download
5. Contact support: If persistent, contact TrustPin support

Diagnostic Information

do {
    try await TrustPin.setup(/* credentials */)
} catch TrustPinErrors.configurationValidationFailed {
    print("configuration validation failed - check credentials and network")
    // Log additional context:
    // - System time
    // - Network conditions
    // - Credential sources
}

Prevention

• Credential management: Securely store and manage public keys
• Time synchronization: Ensure accurate system time via NTP
• Network monitoring: Monitor for network interference

• Validation testing: Regularly test credential validation

The domain is not registered for pinning and enforcement is enabled.

This error occurs only in strict mode when attempting to verify a certificate for a domain that is not configured in your TrustPin pinning configuration. This enforces the security policy that all connections must be explicitly validated.

When This Occurs

• Strict mode only: This error is not thrown in permissive mode
• Unregistered domains: Domain not found in TrustPin dashboard configuration
• Typos in domain: Incorrect domain name or subdomain
• New services: Recently added services not yet registered

Resolution Steps

1. Register domain: Add domain to TrustPin dashboard with appropriate pins
2. Verify domain name: Check for typos or incorrect subdomain
3. Update configuration: Refresh TrustPin configuration if recently added
4. Consider mode: Evaluate if permissive is appropriate

Domain Registration

To register a domain in TrustPin:

1. TrustPin Dashboard: Log into your TrustPin account
2. Add Domain: Configure domain with certificate pins
3. Generate Pins: Create SHA-256 or SHA-512 hashes of certificates
4. Set Expiration: Configure appropriate expiration dates
5. Test Configuration: Verify in staging environment

Example Handling

do {
    try await TrustPin.verify(domain: "new-api.example.com", certificate: cert)
} catch TrustPinErrors.domainNotRegistered {
    // Domain not configured for pinning
    logger.warning("Unregistered domain accessed: \(domain)")

    // Options:
    // 1. Register domain in TrustPin dashboard
    // 2. Switch to permissive mode temporarily
    // 3. Update application to handle unregistered domains
}

Security Considerations

• Intentional restriction: This error enforces your security policy
• Audit trail: Log these events for security monitoring
• Process improvement: May indicate need for better domain management
• Compliance: Helps maintain strict security compliance

Migration Strategy

When implementing strict mode:

// Phase 1: Discovery with permissive mode
TrustPin.set(logLevel: .info)
try await TrustPin.setup(TrustPinConfiguration(
    organizationId: orgId,
    projectId: projectId,
    publicKey: publicKey,
    mode: .permissive
))

// Phase 2: Register discovered domains
// (Use logs to identify all accessed domains)

// Phase 3: Enable strict mode
try await TrustPin.setup(TrustPinConfiguration(
    organizationId: orgId,
    projectId: projectId,
    publicKey: publicKey
    // mode defaults to .strict
))