felectronic_certificates #

Flutter plugin for managing device-stored certificates. Import, sign with, list, and delete PKCS#12 certificates using the Android KeyStore or iOS Keychain.

Features #

Platform Support #

Installation #

dependencies:
  felectronic_certificates: ^1.0.0

Android Setup #

This plugin depends on a bundled AAR (certificatesigner-release.aar) for certificate operations. Add the certificate-signer module to your app's settings.gradle.kts:

// android/settings.gradle.kts
include(":certificate-signer")
project(":certificate-signer").projectDir =
    file("../path-to/felectronic_certificates_android/android/certificate-signer")

The plugin's build.gradle.kts will automatically link the AAR when the :certificate-signer project is found.

iOS Setup #

No additional setup required. The plugin uses the iOS Keychain APIs directly.

Usage #

import 'package:felectronic_certificates/felectronic_certificates.dart';

Import a PKCS#12 Certificate #

import 'dart:io';

final bytes = await File('certificate.p12').readAsBytes();
await importCertificate(
  bytes,
  password: 'cert-password',
  alias: 'My Work Certificate',
);

List All Certificates #

final certs = await getAllCertificates();
for (final cert in certs) {
  print('${cert.displayName} - ${cert.expiryStatus}');
  print('  Serial: ${cert.serialNumber}');
  print('  Issuer: ${cert.issuerName}');
  print('  Usages: ${cert.usageSummary}');
  print('  Expired: ${cert.isExpired}');
}

Select a Default Certificate #

// Open the native picker
final selected = await selectDefaultCertificate();
if (selected != null) {
  print('Selected: ${selected.holderName}');
}

// Or set by serial number directly
await setDefaultCertificateBySerialNumber('AB12CD34');

// Get the current default
final current = await getDefaultCertificate();

// Clear the default selection
await clearDefaultCertificate();

Sign Data #

import 'dart:convert';
import 'dart:typed_data';

final data = Uint8List.fromList(utf8.encode('Data to sign'));

// Sign with the default certificate (SHA-256 with RSA)
final signature = await signWithDefaultCertificate(data);

// Sign with a different algorithm
final ecSignature = await signWithDefaultCertificate(
  data,
  algorithm: CertSignAlgorithm.sha256ec,
);

Delete a Certificate #

// Delete the current default
await deleteDefaultCertificate();

// Delete by serial number
await deleteCertificateBySerialNumber('AB12CD34');

CertificateSession #

CertificateSession wraps a selected certificate for repeated operations without re-selecting each time:

// From the native picker
final session = await CertificateSession.select();
if (session != null) {
  print('Using: ${session.certificate.holderName}');

  final signature = await session.sign(myData);

  // Clear default selection (does not delete the cert)
  await session.clear();

  // Or delete the certificate entirely
  await session.delete();
}

// From the existing default
final session = await CertificateSession.fromDefault();

Signing Algorithms #

Key Usage Types #

Parse from strings:

final usage = CertKeyUsage.tryParse('SIGNING');
final usages = CertKeyUsage.parseUsages('SIGNING;AUTHENTICATION');

DeviceCertificate Extensions #

The DeviceCertificateX extension adds convenience properties:

cert.isExpired;       // Whether the certificate has expired
cert.daysUntilExpiry; // Days remaining (negative if expired)
cert.isExpiringSoon;  // Expires within 30 days
cert.canSign;         // Has CertKeyUsage.signing
cert.canAuthenticate; // Has CertKeyUsage.authentication
cert.canEncrypt;      // Has CertKeyUsage.encryption
cert.usageSummary;    // "Signing, Authentication"
cert.displayName;     // Alias if set, otherwise holderName
cert.expiryStatus;    // "Expires in 45 days", "Expired", etc.

Error Handling #

All errors extend the sealed CertificateError class:

try {
  await signWithDefaultCertificate(data);
} on CertNotSelectedError {
  print('Please select a certificate first');
} on CertSigningError {
  print('Signing failed');
} on CertificateError catch (e) {
  print('Certificate error: ${e.message}');
}

Architecture #

This is a federated Flutter plugin:

Platform communication uses Pigeon for type-safe bindings.