mlkem_native 1.0.1

MLKEM native usage of lib

mlkem_native

A Flutter FFI plugin that provides native ML-KEM (Module Lattice-based Key Encapsulation Mechanism) cryptographic operations. This plugin wraps the mlkem-native library to provide high-performance post-quantum cryptography for Flutter applications.

Features

• Post-Quantum Security: Implements ML-KEM, a quantum-resistant key encapsulation mechanism based on FIPS 203
• Multiple Security Levels: Support for ML-KEM-512, ML-KEM-768, and ML-KEM-1024
• High Performance: Native C/Assembly implementation for optimal performance
• Cross-Platform: Works on Android, iOS, macOS, Linux, and Windows
• Type Safety: Full Dart type safety with proper error handling
• Zero Dependencies: No external cryptographic dependencies required

Supported Platforms

• ✅ Android (ARM64, x86_64)
• ✅ iOS (ARM64, x86_64)
• ✅ macOS (ARM64, x86_64)
• ✅ Linux (x86_64, ARM64)
• ✅ Windows (x86_64)

Security Levels

Security Level	Public Key	Secret Key	Ciphertext	Shared Secret	Security Level
ML-KEM-512	800 bytes	1632 bytes	768 bytes	32 bytes	Level 1
ML-KEM-768	1184 bytes	2400 bytes	1088 bytes	32 bytes	Level 3
ML-KEM-1024	1472 bytes	3168 bytes	1440 bytes	32 bytes	Level 5

Quick Start

Installation

Add mlkem_native to your pubspec.yaml:

dependencies:
  mlkem_native: ^1.0.1

Basic Usage

import 'package:mlkem_native/mlkem_native.dart';

void main() {
  // Create an instance for ML-KEM-768 (recommended for most applications)
  final mlkem = MLKEM768();
  
  // Generate a key pair
  final keyPair = mlkem.generateKeyPair();
  
  // Encapsulate a shared secret using the public key
  final result = mlkem.encapsulate(keyPair.publicKey);
  
  // Decapsulate the shared secret using the secret key
  final sharedSecret = mlkem.decapsulate(result.ciphertext, keyPair.secretKey);
  
  print('Shared secret: ${sharedSecret.length} bytes');
}

Advanced Usage

import 'package:mlkem_native/mlkem_native.dart';

void main() {
  // Choose your security level
  final mlkem512 = MLKEM512();   // Level 1 security
  final mlkem768 = MLKEM768();   // Level 3 security (recommended)
  final mlkem1024 = MLKEM1024(); // Level 5 security
  
  // Generate key pair
  final keyPair = mlkem768.generateKeyPair();
  
  // Encapsulate with error handling
  try {
    final result = mlkem768.encapsulate(keyPair.publicKey);
    print('Ciphertext: ${result.ciphertext.length} bytes');
    print('Shared secret: ${result.sharedSecret.length} bytes');
  } on MLKEMEncapsulationFailedException catch (e) {
    print('Encapsulation failed: ${e.cError}');
  }
  
  // Decapsulate with error handling
  try {
    final sharedSecret = mlkem768.decapsulate(result.ciphertext, keyPair.secretKey);
    print('Decapsulation successful: ${sharedSecret.length} bytes');
  } on MLKEMDecapsulationFailedException catch (e) {
    print('Decapsulation failed: ${e.cError}');
  }
}

API Reference

Classes

MLKEM512, MLKEM768, MLKEM1024

Main classes for ML-KEM operations at different security levels.

Methods:

• KeyPair generateKeyPair({Uint8List? coins}) - Generates a new key pair
• EncapsulationResult encapsulate(Uint8List publicKey, {Uint8List? coins}) - Encapsulates a shared secret
• Uint8List decapsulate(Uint8List ciphertext, Uint8List secretKey) - Decapsulates a shared secret

KeyPair

Represents a public/secret key pair.

Properties:

• Uint8List publicKey - The public key
• Uint8List secretKey - The secret key

EncapsulationResult

Result of an encapsulation operation.

Properties:

• Uint8List ciphertext - The ciphertext
• Uint8List sharedSecret - The generated shared secret

Exceptions

• MLKEMKeyPairGenerationException - Key pair generation failed
• MLKEMPublicKeyWrongLengthException - Public key has wrong length
• MLKEMSecretKeyWrongLengthException - Secret key has wrong length
• MLKEMCiphertextWrongLengthException - Ciphertext has wrong length
• MLKEMEncapsulationFailedException - Encapsulation operation failed
• MLKEMDecapsulationFailedException - Decapsulation operation failed

Project Structure

This project uses the following structure:

• src/: Contains the native source code and CMakeLists.txt for building the dynamic library

  • mlkem-native/: Git submodule containing the mlkem-native library
  • mlkem_native_all.c: Multilevel build configuration for all security levels
  • multilevel_config.h: Configuration file for the multilevel build
  • os_rng.c: Operating system random number generator implementation

• lib/: Contains the Dart code that defines the plugin API

  • mlkem_native.dart: Main plugin interface
  • bindings/: Generated FFI bindings for each security level
    • mlkem512.dart: ML-KEM-512 bindings
    • mlkem768.dart: ML-KEM-768 bindings
    • mlkem1024.dart: ML-KEM-1024 bindings

• Platform folders: Contains build files for each platform

  • android/: Android NDK build configuration
  • ios/: iOS/macOS CocoaPods configuration
  • linux/: Linux CMake configuration
  • windows/: Windows CMake configuration

• example/: Example Flutter application demonstrating usage

Building and Bundling

The plugin uses Flutter's FFI system to build and bundle native code:

plugin:
  platforms:
    android:
      ffiPlugin: true
    ios:
      ffiPlugin: true
    linux:
      ffiPlugin: true
    macos:
      ffiPlugin: true
    windows:
      ffiPlugin: true

Build Systems

• Android: Gradle with Android NDK
• iOS/macOS: Xcode via CocoaPods
• Linux/Windows: CMake

Development

Prerequisites

• Flutter SDK (>=3.3.0)
• Dart SDK (>=3.8.1)
• Platform-specific build tools (Xcode, Android Studio, etc.)

Building

# Build for all platforms
flutter build

# Build for specific platform
flutter build macos
flutter build android
flutter build ios

Security Considerations

Random Number Generation

This plugin uses platform-specific secure random number generators:

• macOS/iOS: SecRandomCopyBytes
• Android: /dev/urandom
• Linux: /dev/urandom
• Windows: BCryptGenRandom

Key Management

• Never store secret keys in plain text
• Use secure storage solutions (Keychain, Keystore, etc.)
• Clear sensitive data from memory when possible
• Validate all inputs before processing

Security Levels

Choose the appropriate security level for your use case:

• ML-KEM-512: Level 1 security (128-bit classical, 64-bit quantum)
• ML-KEM-768: Level 3 security (192-bit classical, 96-bit quantum) - Recommended
• ML-KEM-1024: Level 5 security (256-bit classical, 128-bit quantum)

Versioning

This plugin uses git submodules to include mlkem-native. See VERSIONING.md for details on version management.

Current mlkem-native version: v1.0.0

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the same license as mlkem-native. See LICENSE for details.

Links

• mlkem-native Repository
• ML-KEM Specification
• Post-Quantum Cryptography
• Flutter FFI Documentation

Support

For issues and questions:

• GitHub Issues