TrustPin iOS SDK

TrustPin is a modern, lightweight, and secure iOS/macOS library designed to enforce SSL Certificate Pinning for native applications. Built with Swift Concurrency and following OWASP security recommendations, TrustPin prevents man-in-the-middle (MITM) attacks by ensuring server authenticity at the TLS level.

🚀 Key Features

✅ Modern Swift Concurrency - Built with async/await for seamless integration
✅ Flexible Pinning Modes - Strict validation or permissive mode for development
✅ Multiple Hash Algorithms - SHA-256 and SHA-512 certificate validation
✅ Signed Configuration - Cryptographically signed pinning configurations
✅ Multiple Integration Options - System-wide URLProtocol, URLSessionDelegate, or static helper methods
✅ Intelligent Caching - 10-minute configuration cache with stale fallback
✅ Comprehensive Logging - Configurable log levels for debugging and monitoring
✅ Cross-Platform - iOS, macOS, watchOS, tvOS, and Mac Catalyst support
✅ Enhanced Security - Advanced signature verification with multiple authentication methods

📋 Platform Requirements

Platform	Minimum Version	URLProtocol System-Wide Pinning
iOS	13.0+	✅ Supported
macOS	13.0+	✅ Supported
watchOS	7.0+	✅ Supported
tvOS	13.0+	✅ Supported
Mac Catalyst	13.0+	✅ Supported
visionOS	2.0+	✅ Supported

Required: Swift 5.5+ for async/await support Note: URLProtocol-based features require iOS 13.0+ (available on all supported platforms)

📦 Installation

Swift Package Manager (Recommended)

Add TrustPin to your project using Xcode:

File → Add Package Dependencies

Enter repository URL:

https://github.com/trustpin-cloud/TrustPin-Swift.binary

Select version: 1.2.0 or later

Manual Package.swift

dependencies: [
    .package(url: "https://github.com/trustpin-cloud/TrustPin-Swift.binary", from: "1.2.0")
],
targets: [
    .target(
        name: "YourApp",
        dependencies: [
            .product(name: "TrustPinKit", package: "TrustPin-Swift")
        ]
    )
]

CocoaPods

Add TrustPin to your Podfile:

pod 'TrustPinKit'

Then run:

pod install

The podspec is hosted at TrustPin-Swift.binary and published to the CocoaPods trunk.

🔧 Quick Setup

1. Import and Configure

import TrustPinKit

// Configure TrustPin with your project credentials
try await TrustPin.setup(
    organizationId: "your-org-id",
    projectId: "your-project-id", 
    publicKey: "your-base64-public-key",
    mode: .strict  // Recommended for production
)

💡 Find your credentials in the TrustPin Dashboard

⚠️ Important: TrustPin.setup() must be called only once during your app's lifecycle. Concurrent setup calls are not supported and will throw TrustPinErrors.invalidProjectConfig. If already initialized, subsequent calls will return immediately.

2. Choose Your Pinning Mode

TrustPin offers two validation modes:

Strict Mode (Recommended for Production)

try await TrustPin.setup(
    // ... your credentials
    mode: .strict  // Throws error for unregistered domains
)

Permissive Mode (Development & Testing)

try await TrustPin.setup(
    // ... your credentials  
    mode: .permissive  // Allows unregistered domains to bypass pinning
)

3. System-Wide Protection Control

By default, TrustPin automatically enables certificate pinning for all URLSession requests in your app. This provides the broadest security coverage with zero additional configuration.

Automatic Protection (Default & Recommended)

try await TrustPin.setup(
    organizationId: "your-org-id",
    projectId: "your-project-id",
    publicKey: "your-base64-public-key",
    mode: .strict
    // autoRegisterURLProtocol: true (default)
)

// All URLSession instances now automatically use certificate pinning
// Including URLSession.shared and third-party networking libraries

Manual Control (Advanced)

For advanced scenarios where you need to control when system-wide pinning is active:

try await TrustPin.setup(
    organizationId: "your-org-id",
    projectId: "your-project-id",
    publicKey: "your-base64-public-key",
    mode: .strict,
    autoRegisterURLProtocol: false  // Disable automatic system-wide pinning
)

// Manually enable/disable system-wide pinning when needed
TrustPin.registerURLProtocol()    // Enable
TrustPin.unregisterURLProtocol()  // Disable

💡 Recommendation: Use the default automatic protection unless you have specific requirements for controlling URLProtocol registration timing.

🛠 Integration Approaches

TrustPin offers three different ways to integrate certificate pinning into your application:

Approach	Best For	Setup Complexity	Coverage
System-Wide URLProtocol (Recommended)	Most applications, zero-config after setup	🟢 Minimal	All URLSession requests
URLSessionDelegate	Custom URLSession setups, granular control	🟡 Medium	Specific URLSession instances
Helper Methods	Explicit control, static method preference	🟠 Per-request	Individual requests

When to Choose Each Approach

System-Wide URLProtocol (Default & Recommended)

✅ Broad protection: Automatically secures all URLSession requests
✅ Zero configuration: Works with existing networking code
✅ Third-party compatibility: Protects libraries using URLSession
✅ Maintainability: Single setup call for entire app

URLSessionDelegate

✅ Granular control: Only specific URLSession instances use pinning
✅ Legacy compatibility: Works with older networking patterns
✅ Custom delegation: Integrate with existing URLSessionDelegate code
✅ Selective pinning: Mix pinned and non-pinned sessions in same app

Helper Methods

✅ Explicit requests: Clear intent for which requests use pinning
✅ Static methods: Functional programming style
✅ Migration friendly: Easy drop-in replacements for existing URLSession calls
✅ Testing isolation: Test pinned vs non-pinned requests separately

🛠 Usage Examples

System-Wide Certificate Pinning (Recommended)

The simplest approach - TrustPin automatically protects all HTTPS requests across your entire application:

import TrustPinKit

// In your AppDelegate or App struct
func configureApp() async throws {
    // Setup TrustPin - URLProtocol is automatically registered
    try await TrustPin.setup(
        organizationId: "your-org-id",
        projectId: "your-project-id", 
        publicKey: "your-base64-public-key",
        mode: .strict
    )
    
    // That's it! All URLSession requests now use certificate pinning
}

// Anywhere in your app - pinning works automatically
class NetworkManager {
    func fetchData() async throws -> Data {
        // URLSession.shared automatically uses certificate pinning
        let url = URL(string: "https://api.example.com/data")!
        let (data, _) = try await URLSession.shared.data(from: url)
        return data
    }
    
    func fetchWithCustomSession() async throws -> Data {
        // Custom URLSessions also automatically use certificate pinning
        let session = URLSession(configuration: .ephemeral)
        let url = URL(string: "https://api.example.com/secure")!
        let (data, _) = try await session.data(from: url)
        return data
    }
}

// Third-party libraries using URLSession are also protected!
// Alamofire, URLSession-based HTTP clients, etc. automatically get pinning

🎯 Benefits:

Zero configuration after setup

Protects all URLSession requests system-wide

Works with third-party networking libraries

Automatically secures URLSession.shared and custom sessions

Manual Control (Advanced)

For advanced scenarios where you need control over URLProtocol registration:

// Setup without auto-registration
try await TrustPin.setup(
    organizationId: "your-org-id",
    projectId: "your-project-id",
    publicKey: "your-base64-public-key",
    mode: .strict,
    autoRegisterURLProtocol: false  // Disable auto-registration
)

// Manually register when needed
TrustPin.registerURLProtocol()

// Unregister when no longer needed
TrustPin.unregisterURLProtocol()

URLProtocol Helper Methods (Alternative API)

For scenarios where you prefer explicit control or want to use static helper methods:

import TrustPinKit

class NetworkManager {
    
    // Async/await examples
    func fetchDataWithHelpers() async throws -> Data {
        let url = URL(string: "https://api.example.com/data")!
        let (data, _) = try await TrustPinURLProtocol.data(from: url)
        return data
    }
    
    func downloadFileWithHelpers() async throws -> URL {
        let request = URLRequest(url: URL(string: "https://api.example.com/file.pdf")!)
        let (fileURL, _) = try await TrustPinURLProtocol.download(for: request)
        return fileURL
    }
    
    // Completion handler examples
    func fetchDataWithCompletionHandler() {
        let url = URL(string: "https://api.example.com/data")!
        let task = TrustPinURLProtocol.dataTask(with: url) { data, response, error in
            if let error = error {
                print("Error: \(error)")
                return
            }
            if let data = data {
                print("Received \(data.count) bytes")
            }
        }
        task.resume()
    }
    
    // Custom session with pinning
    func useCustomTrustPinSession() async throws -> Data {
        let session = URLSession.trustPinSession(
            configuration: .ephemeral
        )
        
        let url = URL(string: "https://api.example.com/data")!
        let (data, _) = try await session.data(from: url)
        return data
    }
}

💡 When to use helper methods:

When you need explicit control over individual requests

For codebases that prefer static method calls

When migrating from other networking libraries

For testing scenarios where you want to isolate pinned requests

Automatic URLSession Integration

The traditional delegate-based approach (still fully supported):

import TrustPinKit

class NetworkManager {
    private let trustPinDelegate = TrustPinURLSessionDelegate()
    private lazy var session = URLSession(
        configuration: .default,
        delegate: trustPinDelegate,
        delegateQueue: nil
    )
    
    func fetchData() async throws -> Data {
        let url = URL(string: "https://api.example.com/data")!
        let (data, _) = try await session.data(from: url)
        return data
    }
}

Manual Certificate Verification

For custom networking stacks or certificate inspection:

import TrustPinKit

// Verify a PEM-encoded certificate for a specific domain
let domain = "api.example.com"
let pemCertificate = """
-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END CERTIFICATE-----
"""

do {
    try await TrustPin.verify(domain: domain, certificate: pemCertificate)
    print("✅ Certificate is valid and matches configured pins")
} catch TrustPinErrors.domainNotRegistered {
    print("⚠️ Domain not configured for pinning")
} catch TrustPinErrors.pinsMismatch {
    print("❌ Certificate doesn't match any configured pins")
} catch {
    print("💥 Verification failed: \(error)")
}

Setup and Initialization

import TrustPinKit

class AppDelegate: UIApplicationDelegate {
    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        
        Task {
            do {
                // Setup TrustPin once during app launch
                try await TrustPin.setup(
                    organizationId: "your-org-id",
                    projectId: "your-project-id",
                    publicKey: "your-public-key",
                    mode: .strict
                )
                print("✅ TrustPin initialized successfully")
            } catch {
                print("❌ TrustPin setup failed: \(error)")
            }
        }
        
        return true
    }
}

🔧 Integration Examples

With Alamofire

import Alamofire
import TrustPinKit

// Create a custom SessionDelegate that extends TrustPinURLSessionDelegate
class TrustPinAlamofireDelegate: TrustPinURLSessionDelegate, SessionDelegate {
    // TrustPinURLSessionDelegate handles the certificate validation
}

let trustPinDelegate = TrustPinAlamofireDelegate()
let session = Session(
    configuration: .default,
    delegate: trustPinDelegate,
    rootQueue: DispatchQueue(label: "com.trustpin.alamofire.queue"),
    startRequestsImmediately: true
)

// Use the session for your requests
let response = try await session.request("https://api.example.com/data")
    .validate()
    .serializingData()
    .value

With Custom URLSession

import Foundation
import TrustPinKit

class SecureNetworkClient {
    private let trustPinDelegate = TrustPinURLSessionDelegate()
    private lazy var urlSession: URLSession = {
        let config = URLSessionConfiguration.default
        config.timeoutIntervalForRequest = 30
        return URLSession(configuration: config, delegate: trustPinDelegate, delegateQueue: nil)
    }()
    
    func performSecureRequest(to url: URL) async throws -> (Data, URLResponse) {
        return try await urlSession.data(from: url)
    }
}

🎯 Pinning Modes Explained

Mode	Behavior	Use Case
`.strict`	❌ Throws `TrustPinErrors.domainNotRegistered` for unregistered domains	Production environments where all connections should be validated
`.permissive`	✅ Allows unregistered domains to bypass pinning	Development/Testing or apps connecting to dynamic domains

When to Use Each Mode

Strict Mode (`.strict`)

✅ Production applications
✅ High-security environments
✅ Known, fixed set of API endpoints
✅ Compliance requirements

Permissive Mode (`.permissive`)

✅ Development and staging
✅ Applications with dynamic/unknown endpoints
✅ Gradual migration to certificate pinning
✅ Third-party SDK integrations

📊 Error Handling

TrustPin provides detailed error types for proper handling:

do {
    try await TrustPin.verify(domain: "api.example.com", certificate: pemCert)
} catch TrustPinErrors.domainNotRegistered {
    // Domain not configured in TrustPin (only in strict mode)
    handleUnregisteredDomain()
} catch TrustPinErrors.pinsMismatch {
    // Certificate doesn't match configured pins - possible MITM
    handleSecurityThreat()
} catch TrustPinErrors.allPinsExpired {
    // All pins for domain have expired
    handleExpiredPins()
} catch TrustPinErrors.invalidServerCert {
    // Certificate format is invalid
    handleInvalidCertificate()
} catch TrustPinErrors.invalidProjectConfig {
    // Setup parameters are invalid
    handleConfigurationError()
} catch TrustPinErrors.errorFetchingPinningInfo {
    // Network error fetching configuration
    handleNetworkError()
} catch TrustPinErrors.configurationValidationFailed {
    // configuration signature validation failed
    handleSignatureError()
}

🔍 Logging and Debugging

TrustPin provides comprehensive logging for debugging and monitoring:

// Set log level before setup
await TrustPin.set(logLevel: .debug)

// Available log levels:
// .none     - No logging
// .error    - Errors only  
// .info     - Errors and informational messages
// .debug    - All messages including debug information

🏗 Best Practices

Setup and Initialization

Call TrustPin.setup() only once during app launch (typically in AppDelegate)
Handle setup errors gracefully - don't block app launch if TrustPin fails
Set log level before setup for complete logging coverage
Never call setup concurrently - it's not supported and will throw errors
Use Task/async context for setup in synchronous app lifecycle methods

Security Recommendations

Always use .strict mode in production
Rotate pins before expiration
Monitor pin validation failures
Use HTTPS for all pinned domains
Keep public keys secure and version-controlled

Performance Optimization

Cache TrustPin configuration (handled automatically)
Reuse URLSession instances with TrustPin delegate
Use appropriate log levels (.error or .none in production)
Initialize early to avoid setup delays during first network requests

Development Workflow

Start with .permissive mode during development
Test all endpoints with pinning enabled
Validate pin configurations in staging
Switch to .strict mode for production releases
Use debug logging to troubleshoot pinning issues

🔧 Advanced Configuration

Custom URLSession Configuration

let trustPinDelegate = TrustPinURLSessionDelegate()

let configuration = URLSessionConfiguration.default
configuration.timeoutIntervalForRequest = 30
configuration.timeoutIntervalForResource = 300
configuration.httpMaximumConnectionsPerHost = 4

let session = URLSession(
    configuration: configuration,
    delegate: trustPinDelegate,
    delegateQueue: OperationQueue()
)

Error Recovery Strategies

func performNetworkRequest() async -> Data? {
    do {
        return try await secureNetworkRequest()
    } catch TrustPinErrors.domainNotRegistered {
        // Log security event but continue in permissive mode
        logger.warning("Unregistered domain accessed")
        return try await fallbackNetworkRequest()
    } catch TrustPinErrors.pinsMismatch {
        // This is a serious security issue - do not retry
        logger.critical("Certificate pinning failed - possible MITM attack")
        throw SecurityError.potentialMITMAttack
    }
}

📚 API Reference

Core Classes

TrustPin - Main SDK interface for setup and verification
TrustPinMode - Enum defining pinning behavior modes (.strict, .permissive)
TrustPinURLSessionDelegate - URLSession delegate for automatic validation
TrustPinURLProtocol - URLProtocol implementation for system-wide pinning (iOS 13.0+)
TrustPinErrors - Error types for detailed error handling
TrustPinLogLevel - Logging configuration options (.none, .error, .info, .debug)

Key Methods

Core TrustPin API

// Setup and configuration (standard)
static func setup(organizationId: String, 
                  projectId: String, 
                  publicKey: String, 
                  mode: TrustPinMode = .strict,
                  autoRegisterURLProtocol: Bool = true) async throws

// Setup and configuration with custom CDN
static func setup(organizationId: String, 
                  projectId: String, 
                  publicKey: String, 
                  configurationURL: URL,
                  mode: TrustPinMode = .strict,
                  autoRegisterURLProtocol: Bool = true) async throws

// Manual verification  
static func verify(domain: String, certificate: String) async throws

// System-wide URLProtocol control
static func registerURLProtocol()    // Enable system-wide pinning
static func unregisterURLProtocol()  // Disable system-wide pinning

// Logging configuration
static func set(logLevel: TrustPinLogLevel) async

URLProtocol Helper Methods (iOS 13.0+)

// Async/await data methods with automatic pinning
TrustPinURLProtocol.data(for: URLRequest, using: URLSession? = nil) async throws -> (Data, URLResponse)
TrustPinURLProtocol.data(from: URL, using: URLSession? = nil) async throws -> (Data, URLResponse)

// Async/await download methods with automatic pinning
TrustPinURLProtocol.download(for: URLRequest, using: URLSession? = nil) async throws -> (URL, URLResponse)
TrustPinURLProtocol.download(from: URL, using: URLSession? = nil) async throws -> (URL, URLResponse)

// Completion handler methods with automatic pinning
TrustPinURLProtocol.dataTask(with: URLRequest, using: URLSession? = nil, completionHandler: @escaping @Sendable (Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask
TrustPinURLProtocol.dataTask(with: URL, using: URLSession? = nil, completionHandler: @escaping @Sendable (Data?, URLResponse?, Error?) -> Void) -> URLSessionDataTask

TrustPinURLProtocol.downloadTask(with: URLRequest, using: URLSession? = nil, completionHandler: @escaping @Sendable (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask
TrustPinURLProtocol.downloadTask(with: URL, using: URLSession? = nil, completionHandler: @escaping @Sendable (URL?, URLResponse?, Error?) -> Void) -> URLSessionDownloadTask

// Create URLSession with pinning enabled
URLSession.trustPinSession(configuration: URLSessionConfiguration = .default, 
                          delegate: URLSessionDelegate? = nil, 
                          delegateQueue: OperationQueue? = nil) -> URLSession

🐛 Troubleshooting

Common Issues

Setup Fails with `invalidProjectConfig`

✅ Verify organization ID, project ID, and public key are correct
✅ Check for extra whitespace or newlines in credentials
✅ Ensure public key is properly base64-encoded
✅ Avoid concurrent setup calls - only call TrustPin.setup() once per app lifecycle
✅ Check for multiple setup attempts - if already initialized, subsequent calls return immediately

Certificate Verification Fails

✅ Confirm domain is registered in TrustPin dashboard
✅ Check certificate format (must be PEM-encoded)
✅ Verify pins haven't expired
✅ Test with .permissive mode first

Network Requests Hang

✅ Ensure you're using the correct URLSession delegate
✅ Check for retain cycles with URLSession
✅ Verify network connectivity
✅ Check if URLProtocol is properly registered (when using system-wide pinning)

System-Wide Pinning Not Working

✅ Verify autoRegisterURLProtocol: true was used during setup (default)
✅ Check that you're testing with HTTPS URLs (HTTP is ignored)
✅ Ensure URLProtocol hasn't been unregistered elsewhere in the app
✅ Test with TrustPin.registerURLProtocol() to manually re-register

URLProtocol Helper Methods Not Found

✅ Ensure you're targeting iOS 13.0+ or equivalent platform versions
✅ Check that TrustPin has been set up before using helper methods
✅ Use TrustPinURLProtocol. prefix for static helper methods
✅ Import TrustPinKit module

Debug Steps

Enable debug logging: await TrustPin.set(logLevel: .debug)
Test with permissive mode first
Verify credentials in TrustPin dashboard
Check certificate expiration dates

📖 Documentation

API Documentation: TrustPin iOS SDK Docs
Dashboard: TrustPin Cloud Console
Support: Contact TrustPin

📝 License

This project is licensed under the TrustPin Binary License Agreement - see the LICENSE file for details.

Commercial License: For enterprise licensing or custom agreements, contact [email protected]

Attribution Required: When using this software, you must display "Uses TrustPin™ technology – https://trustpin.cloud" in your application.

🤝 Support & Feedback

We welcome your feedback and questions!

📧 Email: [email protected]
🌐 Website: https://trustpin.cloud
📋 Issues: GitHub Issues

Built with ❤️ by the TrustPin team

Name		Name	Last commit message	Last commit date
Latest commit History 32 Commits
.github		.github
TestApp		TestApp
docs		docs
.gitignore		.gitignore
LICENSE		LICENSE
Package.swift		Package.swift
README.md		README.md
SECURITY.md		SECURITY.md
TrustPinKit.podspec		TrustPinKit.podspec

License

trustpin-cloud/TrustPin-Swift.binary

Folders and files

Latest commit

History

Repository files navigation

TrustPin iOS SDK

🚀 Key Features

📋 Platform Requirements

📦 Installation

Swift Package Manager (Recommended)

Manual Package.swift

CocoaPods

🔧 Quick Setup

1. Import and Configure

2. Choose Your Pinning Mode

Strict Mode (Recommended for Production)

Permissive Mode (Development & Testing)

3. System-Wide Protection Control

Automatic Protection (Default & Recommended)

Manual Control (Advanced)

🛠 Integration Approaches

When to Choose Each Approach

System-Wide URLProtocol (Default & Recommended)

URLSessionDelegate

Helper Methods

🛠 Usage Examples

System-Wide Certificate Pinning (Recommended)

Manual Control (Advanced)

URLProtocol Helper Methods (Alternative API)

Automatic URLSession Integration

Manual Certificate Verification

Setup and Initialization

🔧 Integration Examples

With Alamofire

With Custom URLSession

🎯 Pinning Modes Explained

When to Use Each Mode

Strict Mode (.strict)

Permissive Mode (.permissive)

📊 Error Handling

🔍 Logging and Debugging

🏗 Best Practices

Setup and Initialization

Security Recommendations

Performance Optimization

Development Workflow

🔧 Advanced Configuration

Custom URLSession Configuration

Error Recovery Strategies

📚 API Reference

Core Classes

Key Methods

Core TrustPin API

URLProtocol Helper Methods (iOS 13.0+)

🐛 Troubleshooting

Common Issues

Setup Fails with invalidProjectConfig

Certificate Verification Fails

Network Requests Hang

System-Wide Pinning Not Working

URLProtocol Helper Methods Not Found

Debug Steps

📖 Documentation

📝 License

🤝 Support & Feedback

About

Topics

Resources

License

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 4

Packages 0

Contributors 3

Uh oh!

Languages

Strict Mode (`.strict`)

Permissive Mode (`.permissive`)

Setup Fails with `invalidProjectConfig`

Packages