X509 Certificate Store

A Flutter plugin for Windows and macOS desktop applications that enables adding X.509 certificates to the local certificate store. This plugin provides a simple and efficient way to manage certificates in desktop environments.

Features

Add certificates to the Windows certificate store and macOS Keychain
Support for multiple store locations (ROOT, MY) on Windows
Various certificate addition types:
- Add new certificates only
- Add newer versions of certificates
- Replace existing certificates
Comprehensive error handling with descriptive error codes
Automatic PEM/DER format detection and conversion

Platform Support

macOS	Windows	Linux
✅	✅	🔜

Linux support coming soon!

Installation

dependencies:
  x509_cert_store: ^1.1.0

Or run:

flutter pub add x509_cert_store

Platform-specific Setup

macOS Setup

To use this plugin on macOS, you need to add the Keychain access entitlement to your app:

Add the following to your macos/Runner/DebugProfile.entitlements and macos/Runner/Release.entitlements files:

<key>com.apple.security.keychain</key>
<true/>

If you are creating a new macOS app, make sure to enable the App Sandbox as well:

<key>com.apple.security.app-sandbox</key>
<true/>

Windows Setup

No additional setup is required for Windows.

Usage

import 'package:x509_cert_store/x509_cert_store.dart';

// Create an instance of the plugin
final x509CertStore = X509CertStore();

// Sample certificate in base64 format
const String certificateBase64 = "MIIDKjCCAhKgAwIBAgIQFSHum2++9bhOXjAo4Z7...";

// Add a certificate to the ROOT store
try {
  final result = await x509CertStore.addCertificate(
    storeName: X509StoreName.root,
    certificateBase64: certificateBase64,
    addType: X509AddType.addNew,
  );
  
  if (result.isOk) {
    print("Certificate added successfully");
  } else {
    print("Failed to add certificate: ${result.msg}");
    
    // Check for specific error conditions
    if (result.hasError(X509ErrorCode.alreadyExist)) {
      print("Certificate already exists in the store");
    } else if (result.hasError(X509ErrorCode.canceled)) {
      print("User canceled the certificate installation");
    }
  }
} catch (e) {
  print("An error occurred: $e");
}

API Reference

X509CertStore

The main class for interacting with the certificate store.

Methods

Future<X509ResValue> addCertificate({required X509StoreName storeName, required String certificateBase64, required X509AddType addType})
Adds a certificate to the specified certificate store.

X509StoreName (enum)

Specifies the certificate store location.

root - The trusted root certification authorities store
my - The personal certificate store

X509AddType (enum)

Specifies how to handle the certificate addition.

addNew - Add only if the certificate doesn't exist
addNewer - Add only if the certificate is newer than an existing one
addReplaceExisting - Replace any existing certificate

X509ErrorCode (enum)

Common error codes that might be returned.

canceled - The user canceled the operation
alreadyExist - The certificate already exists in the store
unknown - An unknown error occurred

Platform-specific Behavior

macOS

On macOS, certificates are added to the user's login Keychain regardless of the X509StoreName value provided. The storeName parameter is effectively ignored on macOS since macOS uses a different certificate management system than Windows. Key points for macOS:

All certificates are added to the login Keychain by default
The user may be prompted to enter their password to allow the application to modify the Keychain
Certificate storage location cannot be specified like in Windows (ROOT/MY distinction doesn't apply)
Error codes may differ between platforms, but the plugin normalizes them for consistent error handling

Windows

On Windows, certificates are added to the Windows Certificate Store according to the X509StoreName value specified:

X509StoreName.root adds to the Trusted Root Certification Authorities store
X509StoreName.my adds to the Personal Certificate store
Depending on the certificate and store location, users may see a security prompt asking for confirmation
Administrator privileges may be required for adding certificates to certain stores

Example

Check the /example folder for a complete implementation demonstrating:

Adding certificates with different addition types
Proper error handling
Creating certificate files from base64 strings
Platform-specific configurations

Notes for Developers

If you're contributing to this plugin or integrating it into your application, note that:

For macOS, the plugin requires Keychain access, which is enabled through entitlements
For Windows, the plugin uses the Windows CryptoAPI

License

MIT

Contributing

Contributions are welcome! If you encounter any issues or have feature requests, please file them in the issue tracker.