flutter_ssl_pinning_client

Installation

Add the package to your Flutter project.

flutter pub add flutter_ssl_pinning_client:^2.0.0

Version 2.0.0 requires Dart 3.5 and Flutter 3.24 or later. Review the migration notes if you used 1.x.

Quick Start

Replace the example host and both placeholder pins with independently verified values. The placeholders intentionally reject connections.

import 'package:flutter_ssl_pinning_client/flutter_ssl_pinning_client.dart';

Future<void> main() async {
  final client = SslPinningHttpClient(
    config: SslPinningConfig(
      domainConfigs: {
        'api.example.com': const DomainPinConfig(
          domain: 'api.example.com',
          allowedSHA256Pins: {
            'REPLACE_WITH_VERIFIED_PRIMARY_PIN',
            'REPLACE_WITH_VERIFIED_BACKUP_PIN',
          },
        ),
      },
    ),
  );
  try {
    final response = await client.get(
      Uri.parse('https://api.example.com/account'),
    );
    print('Status: ' + response.statusCode.toString());
  } finally {
    client.close();
  }
}

Configuration

Use exact domain rules where possible. A wildcard such as *.example.com matches one label, not the apex domain or deeper subdomains. Exact matches take precedence.

Pin Rotation

Ship a primary and backup pin before the server changes its certificate or key. Replace the set only after authenticating the new configuration.

config.updatePinsForDomain('api.example.com', {
  'VERIFIED_CURRENT_PIN',
  'VERIFIED_NEXT_PIN',
});

New requests use a fresh connection and the updated pins. An already verified request in flight is not revoked. The package does not fetch, sign, persist or protect remote configuration against rollback.

Security Model

1. Establish TLS with ordinary trust, hostname and certificate validity checks.
2. Read the leaf certificate on that same connection and compare its certificate or SPKI fingerprint.
3. In strict mode, reject a mismatch before handing the connection to the HTTP client.

HTTP is rejected. Redirect responses are returned without automatically following them. Path bypasses and custom HTTP transports are not supported. Report mode never authorizes an invalid TLS certificate.

Pin Formats

Base64 is case sensitive. Certificate renewal changes a certificate pin. An SPKI pin can survive renewal if the server keeps the same key. Only leaf pins are supported.

Known Limitations

Version 2.0.0 uses direct connections without pooling or HTTP proxy support. Consume or cancel response streams and close your client. Physical device testing remains separate from the simulator results below.

API Reference

Explore the public classes, methods and constructors for version 2.0.0.

Example & Tests

The SSL Pinning Lab runs a local HTTPS server inside the example app. It tests certificate pins, SPKI pins, wrong and empty pins, backup pins, report mode, untrusted certificates and redirect handling without using a public service.

Verified using Flutter 3.44.4. A rejected request must produce the expected error and send zero HTTP requests to the local server. This is not a claim of complete security.

git clone https://github.com/lekthedeveloper/flutter_ssl_pinning_client.git
cd flutter_ssl_pinning_client
flutter pub get
flutter test

Frequently Asked Questions