SIMA Flutter Plugin #

A Flutter plugin that enables secure digital signature and authentication flows using the SIMA mobile application.

This package provides a clean, reusable, and production-ready interface for launching the SIMA app from Flutter, sending a cryptographic challenge, and receiving the signed response back into your application.

🔐 All SIMA-specific native logic is encapsulated inside the plugin
🧼 The Flutter app layer stays clean and platform-agnostic

🔗 Package Links #

• 📦 pub.dev: https://pub.dev/packages/sima
• 📄 License: MIT
• 🛠 Platforms: Android, iOS

✨ Features #

• Secure challenge–response signing flow
• Native SIMA app integration
• Android & iOS support
• Minimal and clean Flutter API
• Asset-based logo handling (path only)
• No Base64 handling required in Flutter
• Plugin-managed native callbacks
• Production-ready architecture

📦 Installation #

Add the package from pub.dev:

dependencies:
  sima: ^1.0.1

Then run:

flutter pub get

🔐 Important Credentials Notice #

Before integrating SIMA, you must obtain the following credentials:

• clientId
• masterKey

These credentials are NOT generated by the plugin.

⚠️ Both clientId and masterKey must be provided by SIMA platform developers.
They uniquely identify your application and are required for signature validation.

Security Rule #

• clientId → can be safely used in the mobile application
• masterKey → MUST NEVER be stored in Flutter or mobile apps
  It must be stored and used only on your backend.

🧠 Overall Secure Authentication Flow (loginSafe) #

The recommended authentication flow uses the loginSafe() method and follows a clear separation of responsibilities between the mobile app, backend, and SIMA app.

🔁 Step-by-Step Flow #

1️⃣ Mobile App (Flutter)

• Generates a secure random challenge using:

  final challenge = Sima.createChallenge();
  

• Sends the Base64-encoded challenge to your backend.

2️⃣ Backend (Your Server)

• Receives the challenge from the mobile app
• Uses the masterKey (provided by SIMA) to generate an HMAC signature
• Optionally:
  • Stores the challenge temporarily
  • Marks it as used after successful authentication (anti-replay protection)
• Returns the generated signature to the mobile app

3️⃣ Mobile App (Flutter)

• Receives the signature from backend
• Calls:

final response = await Sima.loginSafe(
  clientId: 'YOUR_CLIENT_ID',
  returnScheme: 'your-app-scheme',
  serviceName: 'Your App Name',
  logoPath: 'assets/logo.png',
  challenge: challenge,
  signature: signature,
);

4️⃣ SIMA Mobile Application

• Verifies the signature and challenge
• Prompts the user for authentication (PIN / biometrics)
• Signs the challenge using the user's SIMA certificate
• Redirects back to your app with:
  • signed data
  • certificate
  • status

5️⃣ Final Result (Your App)

• Receives the result through the plugin
• Sends signature + certificate to backend (optional but recommended)
• Backend verifies the signature and completes authentication

🧩 Flow Diagram (Conceptual) #

Flutter App
   |
   |-- createChallenge()
   |
   |---- challenge ----> Backend
   |                      |
   |                      |-- sign(challenge, masterKey)
   |                      |
   |<--- signature -------|
   |
   |-- loginSafe(challenge, signature)
   |
SIMA App
   |
   |-- user authentication
   |-- certificate signing
   |
   |--> callback
   |
Flutter App

🎨 Asset Setup (Logo) #

The SIMA plugin requires a logo image to be displayed inside the SIMA application.

1️⃣ Add the logo to your Flutter assets #

flutter:
  assets:
    - assets/logo.png

Supported formats:

• PNG
• JPG

⚠️ SVG is not supported for SIMA logos.

2️⃣ Pass only the asset path #

logoPath: 'assets/logo.png'

The plugin will load and convert the image internally.

🚀 Usage (Secure Example) #

final challenge = Sima.createChallenge();

final signature = await signatureProvider.sign(
  challenge.toBase64(),
);

ℹ️ Note:
This call represents a network request to your backend service.
The backend generates the signature using the SIMA masterKey and returns it to the mobile app.
The masterKey never exists in Flutter or on the device.

final response = await Sima.loginSafe(
  clientId: 'YOUR_CLIENT_ID',
  returnScheme: 'your-app-scheme',
  serviceName: 'Your App Name',
  logoPath: 'assets/logo.png',
  challenge: challenge,
  signature: signature,
);

❗ Error Handling #

🔐 Security Notes #

• Never hardcode secrets in Flutter UI code
• Store the SIMA masterKey only on backend
• Always validate SIMA responses server-side
• Use anti-replay protection for challenges

⚠️ Legacy API #

The login() method is provided only for backward compatibility and demos.

❗ Do NOT use it in production.
Always prefer createChallenge() + loginSafe().

📄 License #

MIT License

⚠️ Disclaimer #

This plugin is not officially affiliated with SIMA.

The example application uses a mock signature provider. In real applications, the signature must be generated on your backend using your SIMA master key.