ffi-patterns

djx-y-z's avatarfrom djx-y-z

Dart FFI patterns and best practices for this project. Use when writing FFI code, working with native memory, creating wrappers, or implementing new native bindings.

⭐2stars🔀1forks📁View on GitHub🕐Updated Jan 10, 2026

When & Why to Use This Skill

This Claude skill provides standardized Dart FFI (Foreign Function Interface) patterns and best practices for seamless native library integration. It streamlines the process of writing FFI code, managing native memory, and creating robust Dart wrappers, with a specific focus on security and memory safety for high-performance projects like liboqs_dart.

Use Cases

  • Developing Native Bindings: Use proven templates to correctly map C functions and structures to Dart, reducing boilerplate and errors.
  • Native Memory Management: Implement reliable allocation and deallocation patterns, including the use of Finalizers to prevent native memory leaks during garbage collection.
  • Secure Data Handling: Apply security-first practices for cryptographic applications, such as zeroing sensitive memory and using constant-time comparisons.
  • Type Conversion: Efficiently bridge the gap between Dart types (Uint8List, String) and native pointers (Pointer<Uint8>, Utf8) using optimized utility methods.
  • Wrapper Class Implementation: Create clean, object-oriented Dart APIs that safely encapsulate complex native pointer logic and lifecycle management.
nameffi-patterns
descriptionDart FFI patterns and best practices for this project. Use when writing FFI code, working with native memory, creating wrappers, or implementing new native bindings.

FFI Patterns for liboqs_dart

Patterns and templates for writing correct Dart FFI code in this project.

Memory Allocation

Allocate Bytes

final ptr = LibOQSUtils.allocateBytes(length);
try {
  // Use ptr...
} finally {
  LibOQSUtils.freePointer(ptr);  // or secureFreePointer for secrets
}

Convert Uint8List to Pointer

final ptr = LibOQSUtils.uint8ListToPointer(data);
try {
  // Use ptr...
} finally {
  LibOQSUtils.freePointer(ptr);
}

Convert Pointer to Uint8List

final result = LibOQSUtils.pointerToUint8List(ptr, length);
// Result is a copy - safe to free ptr after this

String Handling

final namePtr = algorithmName.toNativeUtf8();
try {
  final result = oqs.OQS_KEM_new(namePtr.cast());
  // ...
} finally {
  LibOQSUtils.freePointer(namePtr);
}

Wrapper Class Pattern

// Finalizer for automatic cleanup
final Finalizer<Pointer<oqs.OQS_KEM>> _kemFinalizer = Finalizer(
  (ptr) => oqs.OQS_KEM_free(ptr),
);

class KEM {
  late final Pointer<oqs.OQS_KEM> _ptr;
  bool _disposed = false;

  KEM._(this._ptr) {
    // Attach finalizer for GC cleanup
    _kemFinalizer.attach(this, _ptr, detach: this);
  }

  void _checkDisposed() {
    if (_disposed) {
      throw StateError('Instance has been disposed');
    }
  }

  // Factory constructor
  static KEM create(String algorithmName) {
    LibOQSBase.init();  // Auto-initialize library

    final namePtr = algorithmName.toNativeUtf8();
    try {
      final ptr = oqs.OQS_KEM_new(namePtr.cast());
      if (ptr == nullptr) {
        throw LibOQSException('Failed to create instance');
      }
      return KEM._(ptr);
    } finally {
      LibOQSUtils.freePointer(namePtr);
    }
  }

  // Dispose pattern
  void dispose() {
    if (!_disposed) {
      oqs.OQS_KEM_free(_ptr);      // 1. Free native memory
      _kemFinalizer.detach(this);   // 2. Detach finalizer
      _disposed = true;              // 3. Set flag
    }
  }
}

Data Class with Secrets

final Finalizer<Uint8List> _secretFinalizer = Finalizer((data) {
  LibOQSUtils.zeroMemory(data);
});

class KeyPair {
  final Uint8List publicKey;
  final Uint8List secretKey;

  KeyPair({required this.publicKey, required this.secretKey}) {
    // Auto-zero secret on GC (defense-in-depth)
    _secretFinalizer.attach(this, secretKey, detach: this);
  }

  /// Zero secrets immediately (recommended)
  void clearSecrets() {
    LibOQSUtils.zeroMemory(secretKey);
  }

  /// Safe: only exposes public key
  String get publicKeyBase64 => base64Encode(publicKey);

  /// **Security Warning:** Exports SECRET KEY in plaintext!
  Map<String, String> toStrings() {
    return {
      'publicKey': base64Encode(publicKey),
      'secretKey': base64Encode(secretKey),
    };
  }
}

Calling Native Functions

From Struct Field

// 1. Validate function pointer
if (_ptr.ref.keypair == nullptr) {
  throw LibOQSException('Function pointer is null');
}

// 2. Convert to Dart function
final keypairFn = _ptr.ref.keypair.asFunction<
  int Function(Pointer<Uint8> publicKey, Pointer<Uint8> secretKey)
>();

// 3. Allocate output buffers
final publicKey = LibOQSUtils.allocateBytes(publicKeyLength);
final secretKey = LibOQSUtils.allocateBytes(secretKeyLength);

try {
  // 4. Call function
  final result = keypairFn(publicKey, secretKey);

  if (result != 0) {
    throw LibOQSException('Operation failed', result);
  }

  // 5. Copy results to Dart
  return KeyPair(
    publicKey: LibOQSUtils.pointerToUint8List(publicKey, publicKeyLength),
    secretKey: LibOQSUtils.pointerToUint8List(secretKey, secretKeyLength),
  );
} finally {
  // 6. Free native memory (secure for secrets!)
  LibOQSUtils.freePointer(publicKey);
  LibOQSUtils.secureFreePointer(secretKey, secretKeyLength);
}

Direct Library Call

final count = oqs.OQS_KEM_alg_count();  // Simple - no cleanup needed

final namePtr = oqs.OQS_KEM_alg_identifier(i);
if (namePtr != nullptr) {
  final name = namePtr.cast<Utf8>().toDartString();
  // Don't free namePtr - it's a static string from library
}

Error Handling

try {
  final result = nativeFunction(args);
  if (result != 0) {
    throw LibOQSException('Operation failed', result);
  }
} on LibOQSException {
  rethrow;  // Preserve our exceptions
} catch (e) {
  throw LibOQSException('Unexpected error: $e');
}

Utilities Reference

Method Use For
LibOQSUtils.allocateBytes(n) Allocate n bytes
LibOQSUtils.freePointer(ptr) Free non-sensitive memory
LibOQSUtils.secureFreePointer(ptr, len) Free sensitive memory (zeros first)
LibOQSUtils.uint8ListToPointer(list) Copy Dart list to native
LibOQSUtils.pointerToUint8List(ptr, len) Copy native to Dart list
LibOQSUtils.zeroMemory(list) Zero a Dart Uint8List
LibOQSUtils.constantTimeEquals(a, b) Compare secrets safely
LibOQSUtils.validateAlgorithmName(name) Check algorithm name format