ffi-patterns
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.
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.
| name | ffi-patterns |
|---|---|
| description | 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. |
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 |