TrustPin class

TrustPin SSL certificate pinning SDK for Flutter applications.

TrustPin provides SSL certificate pinning functionality to prevent man-in-the-middle (MITM) attacks by validating server certificates against pre-configured public key pins. The library supports both strict and permissive validation modes to accommodate different security requirements.

Overview

TrustPin uses JSON Web Signature (JWS) based configuration to securely deliver pinning configurations to your Flutter application. The SDK fetches signed pinning configuration from the TrustPin CDN and validates certificates against SHA-256 or SHA-512 hashes.

Key Features

• JWS-based Configuration: Fetches signed pinning configuration from TrustPin CDN
• Certificate Validation: Supports SHA-256 and SHA-512 certificate hashing
• Signature Verification: Validates JWS signatures using ECDSA P-256
• Intelligent Caching: Caches configuration for 10 minutes with stale fallback
• Thread Safety: All operations are thread-safe and work with Flutter's async model
• Configurable Logging: Multiple log levels for debugging and monitoring
• Cross-Platform: Works on iOS, Android, and macOS with native implementations

Basic Usage

import 'package:trustpin_sdk/trustpin_sdk.dart';

// TrustPin is a singleton - no instantiation needed

// Initialize TrustPin with your project credentials
await TrustPin.setup(
  organizationId: 'your-org-id',
  projectId: 'your-project-id',
  publicKey: 'your-base64-public-key',
  mode: TrustPinMode.strict, // Use strict mode in production
);

// Verify a certificate manually
final pemCertificate = '''
-----BEGIN CERTIFICATE-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...
-----END CERTIFICATE-----
''';

try {
  await TrustPin.verify('api.example.com', pemCertificate);
  print('Certificate is valid!');
} catch (e) {
  print('Certificate validation failed: $e');
}

Integration with HTTP Clients

For automatic certificate validation, integrate TrustPin with your HTTP client:

import 'dart:io';
import 'package:http/http.dart' as http;

// Custom HttpClient with certificate callback
class TrustPinHttpClient extends http.BaseClient {
  final http.Client _client = http.Client();
  final TrustPinSDK _trustPin = TrustPinSDK();

  @override
  Future<http.StreamedResponse> send(http.BaseRequest request) async {
    // Validate certificate before making request
    final uri = request.url;
    if (uri.scheme == 'https') {
      // Get certificate from connection and verify
      // Implementation depends on your HTTP client setup
    }
    return _client.send(request);
  }
}

Pinning Modes

• TrustPinMode.strict: Throws errors for unregistered domains (recommended for production)
• TrustPinMode.permissive: Allows unregistered domains to bypass pinning (development/testing)

Error Handling

TrustPin provides detailed error information through TrustPinException for proper error handling and security monitoring. All errors include specific error codes that can be checked programmatically:

try {
  await trustPin.verify('api.example.com', certificate);
} on TrustPinException catch (e) {
  if (e.isDomainNotRegistered) {
    print('Domain not configured for pinning');
  } else if (e.isPinsMismatch) {
    print('Certificate doesn\'t match configured pins');
  } else if (e.isAllPinsExpired) {
    print('All pins for this domain have expired');
  }
  // Handle other error types...
}

Security Considerations

• Production: Always use TrustPinMode.strict mode to ensure all connections are validated
• Development: Use TrustPinMode.permissive mode to allow connections to unregistered domains
• Credentials: Keep your public key secure and never commit it to version control in plain text
• Network: Ensure your app can reach https://cdn.trustpin.cloud for configuration updates

Thread Safety

All TrustPin operations are thread-safe and can be called from any isolate. Internal operations are performed on appropriate background threads through the native platform implementations.

• Note: Always call setup before performing certificate verification.
• Important: Use TrustPinMode.strict mode in production environments for maximum security.