connect_secure 🔒

A Dart/Flutter package to add SSL Pinning support in your applications. It ensures that your app only communicates with trusted servers by validating server certificates or public key fingerprints.

This helps protect against MITM (Man-in-the-Middle) attacks and ensures secure communication.

✨ Features

✅ SSL Pinning with SHA-256 certificate fingerprints
✅ Works with Dio and http (IOClient)
✅ Host-based pinning and fingerprint normalization (colon/space-insensitive)
✅ Easy to configure and integrate
✅ Lightweight & customizable
🆕 Certificate Discovery - Automatically extract fingerprints from servers
🆕 Certificate Monitoring - Real-time health monitoring and expiry alerts
🆕 Certificate Validation - Validate certificates against expected fingerprints
🆕 Certificate Rotation - Seamless certificate updates and rotation
🆕 CLI Tools - Command-line interface for certificate management
🆕 Multi-Environment Support - Manage certificates across different environments

🚀 Installation

Add the dependency in your pubspec.yaml:

dependencies:
  connect_secure: ^1.0.1

Then run:

flutter pub get

📖 Usage

Import the package:

import 'package:connect_secure/connect_secure.dart';

Example: Using SSL Pinning with Dio

import 'package:dio/dio.dart';
import 'package:connect_secure/connect_secure.dart';

void main() async {
  final dio = Dio();

  // Attach SSL Pinning adapter
  dio.httpClientAdapter = DioSslPinning(
    allowedFingerprints: [
      // Add your server's SHA-256 certificate fingerprint (colon/space format allowed)
      "12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF",
    ],
    // Optionally pin different hosts to different fingerprints
    fingerprintsByHost: {
      "api.your-secure-api.com": [
        "12 34 56 78 90 ab cd ef 12 34 56 78 90 ab cd ef 12 34 56 78 90 ab cd ef 12 34 56 78 90 ab cd ef",
      ],
    },
  );

  try {
    final response = await dio.get("https://your-secure-api.com");
    print("✅ Response: ${response.data}");
  } catch (e) {
    print("❌ SSL Pinning validation failed: $e");
  }
}

Example: Using SSL Pinning with http (IOClient)

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

void main() async {
  final client = createPinnedHttpClient(
    allowedFingerprints: [
      "12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF",
    ],
    fingerprintsByHost: {
      "example.com": ["f9b2f8d74c6f5f8e8c0b9e0d12345abcd..."],
    },
  );

  final response = await client.get(Uri.parse('https://example.com'));
  print(response.statusCode);
}

Example: Using raw dart:io HttpClient

import 'dart:convert';
import 'package:connect_secure/connect_secure.dart';

void main() async {
  final httpClient = SecureHttpClient(
    allowedFingerprints: [
      "12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF:12:34:56:78:90:AB:CD:EF",
    ],
    fingerprintsByHost: {
      "example.com": ["f9b2f8d74c6f5f8e8c0b9e0d12345abcd..."],
    },
  );

  final res = await httpClient.get(Uri.parse('https://example.com'));
  final body = await res.transform(utf8.decoder).join();
  print(body);
}

🔒 Security Best Practices

1. Obtaining Certificate Fingerprints

To get the SHA-256 fingerprint of your server's certificate:

# Using OpenSSL
openssl s_client -connect your-domain.com:443 -servername your-domain.com < /dev/null 2>/dev/null | openssl x509 -fingerprint -sha256 -noout

# Using curl
curl -s "https://your-domain.com" | openssl s_client -connect your-domain.com:443 -servername your-domain.com 2>/dev/null | openssl x509 -fingerprint -sha256 -noout

2. Error Handling

Always handle SslPinningException in your application:

try {
  final response = await dio.get("https://api.example.com");
  print("✅ Secure connection established");
} on SslPinningException catch (e) {
  print("❌ SSL Pinning failed: ${e.message}");
  print("Host: ${e.host}");
  print("Rejected fingerprint: ${e.rejectedFingerprint}");
  print("Allowed fingerprints: ${e.allowedFingerprints}");
  // Handle the security violation appropriately
} catch (e) {
  print("❌ Other error: $e");
}

3. Multiple Fingerprints

Always pin multiple certificates for redundancy:

final allowedFingerprints = [
  "current_certificate_fingerprint",
  "backup_certificate_fingerprint", // For certificate rotation
  "intermediate_certificate_fingerprint",
];

4. Certificate Rotation

Plan for certificate updates by:

Pinning both current and backup certificates
Implementing a secure update mechanism
Monitoring certificate expiration dates

🛠️ CLI Tools

The package includes powerful CLI tools for certificate management:

Certificate Discovery

# Discover certificates from a server
connect_secure discover --host api.example.com

# Output in different formats
connect_secure discover --host api.example.com --json
connect_secure discover --host api.example.com --yaml
connect_secure discover --host api.example.com --dart --output config.dart

Certificate Monitoring

# Check certificate health once
connect_secure monitor --host api.example.com

# Continuous monitoring
connect_secure monitor --host api.example.com --daemon --interval 30

# Monitor with JSON output
connect_secure monitor --host api.example.com --json --output logs.json

Certificate Validation

# Validate certificate
connect_secure validate --host api.example.com

# Validate against specific fingerprints
connect_secure validate --host api.example.com --fingerprints "abc123,def456"

Certificate Rotation

# Dry run certificate rotation
connect_secure rotate --host api.example.com --dry-run

# Rotate certificates
connect_secure rotate --host api.example.com --new-fingerprints "abc123,def456"

📂 Example Project

See the example for a full working demo.

Advanced Certificate Management

Check out certificate_lifecycle_example.dart for advanced certificate lifecycle management features.

🛠 Roadmap

x Enhanced error handling with detailed exception information
x Comprehensive test coverage
x Complete API documentation
Support multiple SSL pinning modes (certificate, public key)
Add automatic fingerprint generation tool
Certificate chain validation options

🤝 Contributing

Contributions are welcome!

Fork the repo
Create your feature branch (git checkout -b feature/my-feature)
Commit your changes (git commit -m 'Add some feature')
Push to the branch (git push origin feature/my-feature)
Create a Pull Request

📜 License

This project is licensed under the MIT License. See the LICENSE file for details.

👨‍💻 Author

Neethu KT

GitLab: connect_secure