Added docs

Author: LucazzP

README.md

@@ -1,42 +1,82 @@
-<!-- 
-This README describes the package. If you publish this package to pub.dev,
-this README's contents appear on the landing page for your package.
+> Minimum Dart SDK 3.10 (Flutter 3.38) with Native Assets/hooks support.
 
-For information about how to write a good package README, see the guide for
-[writing package pages](https://dart.dev/tools/pub/writing-package-pages). 
+This package builds OpenSSL from source and exposes its full C surface directly to Dart via FFI. There are no Dart-side abstractions: call the OpenSSL APIs as you would in C, manage memory manually, and follow the official OpenSSL documentation for usage and lifetime rules.
 
-For general information about developing packages, see the Dart guide for
-[creating packages](https://dart.dev/guides/libraries/create-packages)
-and the Flutter guide for
-[developing packages and plugins](https://flutter.dev/to/develop-packages). 
--->
+## What you get
 
-TODO: Put a short description of the package here that helps potential users
-know whether this package might be useful for them.
-
-## Features
-
-TODO: List what your package can do. Maybe include images, gifs, or videos.
+- Full OpenSSL C API available in Dart (headers mirrored into FFI bindings).
+- Native assets build step that compiles OpenSSL locally the first time you run the app.
+- No opinionated wrappers; you stay in control of allocation and cleanup.
 
 ## Getting started
 
-TODO: List prerequisites and provide or point to information on how to
-start using the package.
+1) Add the package: `dart pub add openssl` (or add it to your `pubspec.yaml`).
+2) Run your app once to trigger the native build (about 1 minute on first run).
 
-## Usage
+## Using the bindings
 
-TODO: Include short and useful examples for package users. Add longer examples
-to `/example` folder. 
+Import and call OpenSSL functions directly; the generated bindings live under `lib/src/third_party/openssl.g.dart`.
 
 ```dart
-const like = 'sample';
+import 'dart:convert';
+import 'dart:typed_data';
+import 'package:ffi/ffi.dart';
+import 'package:openssl/openssl.dart' as openssl;
+
+Uint8List aes(Uint8List input, Uint8List key, Uint8List iv, {required bool encrypt}) {
+  return using((arena) {
+    final ctx = openssl.EVP_CIPHER_CTX_new();
+    final inPtr = arena.allocate<Uint8>(input.isEmpty ? 1 : input.length);
+    final keyPtr = arena.allocate<Uint8>(key.length);
+    final ivPtr = arena.allocate<Uint8>(iv.length);
+    final outPtr = arena.allocate<Uint8>(input.length + openssl.EVP_MAX_BLOCK_LENGTH);
+    final outLenPtr = arena.allocate<Int>(2);
+
+    inPtr.asTypedList(input.length).setAll(0, input);
+    keyPtr.asTypedList(key.length).setAll(0, key);
+    ivPtr.asTypedList(iv.length).setAll(0, iv);
+
+    final initResult = encrypt
+        ? openssl.EVP_EncryptInit_ex(ctx, openssl.EVP_aes_256_cbc(), nullptr, keyPtr.cast(), ivPtr.cast())
+        : openssl.EVP_DecryptInit_ex(ctx, openssl.EVP_aes_256_cbc(), nullptr, keyPtr.cast(), ivPtr.cast());
+    if (initResult != 1) throw StateError('init failed');
+
+    final updateResult = encrypt
+        ? openssl.EVP_EncryptUpdate(ctx, outPtr.cast(), outLenPtr, inPtr.cast(), input.length)
+        : openssl.EVP_DecryptUpdate(ctx, outPtr.cast(), outLenPtr, inPtr.cast(), input.length);
+    if (updateResult != 1) throw StateError('update failed');
+
+    var outLen = outLenPtr.value;
+    final finalResult = encrypt
+        ? openssl.EVP_EncryptFinal_ex(ctx, outPtr.elementAt(outLen).cast(), outLenPtr)
+        : openssl.EVP_DecryptFinal_ex(ctx, outPtr.elementAt(outLen).cast(), outLenPtr);
+    if (finalResult != 1) throw StateError('final failed');
+
+    outLen += outLenPtr.value;
+    return Uint8List.fromList(outPtr.asTypedList(outLen));
+  });
+}
+
+void main() {
+  final key = utf8.encode('Nc92PMoPjcIls5QoXeki5yIPuhjjWMcx');
+  final iv = utf8.encode('1234567890123456');
+  final plaintext = utf8.encode('Secret message for AES-256-CBC');
+
+  final encrypted = aes(plaintext, Uint8List.fromList(key), Uint8List.fromList(iv), encrypt: true);
+  final decrypted = aes(encrypted, Uint8List.fromList(key), Uint8List.fromList(iv), encrypt: false);
+
+  print('cipher (b64): ${base64.encode(encrypted)}');
+  print('roundtrip: ${utf8.decode(decrypted)}');
+}
 ```
 
-## Additional information
+Remember: follow OpenSSL docs for allocation/free patterns (`OPENSSL_free`, `EVP_*` lifecycle, etc.).
+
+## Build notes and roadmap
 
-TODO: Tell users more about the package: where to find more information, how to 
-contribute to the package, how to file issues, what response they can expect 
-from the package authors, and more.
+- First build compiles OpenSSL; subsequent runs are faster. The goal is to ship precompiled binaries later to skip this step.
+- Native assets require Flutter 3.38+/Dart 3.10+ to run the hook pipeline.
 
+## Contributing
 
-`git submodule update --init`
+For local builds, regenerating bindings, and working with the OpenSSL submodule, see `contrib.md`.

contrib.md

@@ -0,0 +1,8 @@
+## Contributing and local builds
+
+- Tooling: Dart 3.10+ / Flutter 3.38+ with Native Assets; standard C build toolchain (perl + make/clang on macOS/Linux; MSVC + perl + jom on Windows—hook can download perl/jom if missing).
+- Clone with submodules: `git clone --recurse-submodules <repo>` (or `git submodule update --init` after cloning).
+- Install deps: `dart pub get`.
+- Regenerate bindings after updating headers: `dart run tool/ffigen.dart`.
+- Build the native assets: run the app (`dart run`) and the hook compiles OpenSSL (first build ~1 minute).
+- Tests: `dart test`.

example/main.dart

@@ -0,0 +1,61 @@
+import 'dart:convert';
+import 'dart:ffi';
+import 'dart:typed_data';
+
+import 'package:ffi/ffi.dart';
+import 'package:openssl/openssl.dart' as openssl;
+
+Uint8List aes(Uint8List input, Uint8List key, Uint8List iv, {required bool encrypt}) {
+  if (key.length != 32) {
+    throw ArgumentError.value(key.length, 'key', 'Key must be 32 bytes for AES-256-CBC');
+  }
+  if (iv.length != 16) {
+    throw ArgumentError.value(iv.length, 'iv', 'IV must be 16 bytes for AES-256-CBC');
+  }
+
+  return using((arena) {
+    final ctx = openssl.EVP_CIPHER_CTX_new();
+    if (ctx == nullptr) throw StateError('Failed to create EVP_CIPHER_CTX');
+
+    final inPtr = arena.allocate<Uint8>(input.isEmpty ? 1 : input.length);
+    final keyPtr = arena.allocate<Uint8>(key.length);
+    final ivPtr = arena.allocate<Uint8>(iv.length);
+    final outPtr = arena.allocate<Uint8>(input.length + openssl.EVP_MAX_BLOCK_LENGTH);
+    final outLenPtr = arena.allocate<Int>(2);
+
+    inPtr.asTypedList(input.length).setAll(0, input);
+    keyPtr.asTypedList(key.length).setAll(0, key);
+    ivPtr.asTypedList(iv.length).setAll(0, iv);
+
+    final initResult = encrypt
+        ? openssl.EVP_EncryptInit_ex(ctx, openssl.EVP_aes_256_cbc(), nullptr, keyPtr.cast(), ivPtr.cast())
+        : openssl.EVP_DecryptInit_ex(ctx, openssl.EVP_aes_256_cbc(), nullptr, keyPtr.cast(), ivPtr.cast());
+    if (initResult != 1) throw StateError('OpenSSL AES init step failed: $initResult');
+
+    final updateResult = encrypt
+        ? openssl.EVP_EncryptUpdate(ctx, outPtr.cast(), outLenPtr, inPtr.cast(), input.length)
+        : openssl.EVP_DecryptUpdate(ctx, outPtr.cast(), outLenPtr, inPtr.cast(), input.length);
+    if (updateResult != 1) throw StateError('OpenSSL AES update step failed: $updateResult');
+
+    var outLen = outLenPtr.value;
+    final finalResult = encrypt
+        ? openssl.EVP_EncryptFinal_ex(ctx, outPtr.elementAt(outLen).cast(), outLenPtr)
+        : openssl.EVP_DecryptFinal_ex(ctx, outPtr.elementAt(outLen).cast(), outLenPtr);
+    if (finalResult != 1) throw StateError('OpenSSL AES final step failed: $finalResult');
+
+    outLen += outLenPtr.value;
+    return Uint8List.fromList(outPtr.asTypedList(outLen));
+  });
+}
+
+void main() {
+  final key = utf8.encode('Nc92PMoPjcIls5QoXeki5yIPuhjjWMcx');
+  final iv = utf8.encode('1234567890123456');
+  final plaintext = utf8.encode('Secret message for AES-256-CBC');
+
+  final encrypted = aes(Uint8List.fromList(plaintext), Uint8List.fromList(key), Uint8List.fromList(iv), encrypt: true);
+  final decrypted = aes(encrypted, Uint8List.fromList(key), Uint8List.fromList(iv), encrypt: false);
+
+  print('cipher (base64): ${base64.encode(encrypted)}');
+  print('roundtrip text: ${utf8.decode(decrypted)}');
+}