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
• Multiple Instances: Use shared for a single-project app, or instance for libraries and multi-tenant setups

Basic Usage

import 'package:trustpin_sdk/trustpin_sdk.dart';

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

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

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

Multiple Instances

Libraries or multi-tenant apps can use named instances to avoid conflicts:

final pin = TrustPin.instance('com.mylib.networking');
await pin.setup(config);
await pin.verify('api.example.com', pem);

Integration with HTTP Clients

For automatic certificate validation, use the built-in HTTP interceptors:

// With Dio (uses TrustPin.shared by default)
final dio = Dio();
dio.interceptors.add(TrustPinDioInterceptor());

// With a named instance
dio.interceptors.add(TrustPinDioInterceptor(instance: pin));

// With http package
final client = TrustPinHttpClient.create();
final response = await client.get(Uri.parse('https://api.example.com'));
client.close();

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.shared.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.