TrustPin class

TrustPin SSL certificate pinning SDK for Flutter applications.

Validates server certificates against pinning configuration to mitigate man-in-the-middle (MITM) attacks. Supports strict and permissive modes.

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

• Use TrustPinMode.strict in production.

• Keep your public key out of source control as plain text.

• Note: Always call setup before performing certificate verification.