initial

README.md

@@ -0,0 +1,131 @@
+# Argon2id for Elixir
+
+Fast and secure Argon2 password hashing library for Elixir.
+
+## Features
+
+- Uses the pure Rust implementation of Argon2
+- Only Argon2i implementation (version 0x13) at the moment
+- Built-in security presets (OWASP, Strong, Test/Unsafe)
+
+## Installation
+
+Add `argon2id_elixir` to your list of dependencies in `mix.exs`:
+
+```elixir
+def deps do
+  [
+    {:argon2id_elixir, "~> 0.1.0"}
+  ]
+end
+```
+
+Ensure you have Rust installed, as it's required for compilation:
+
+```bash
+# On Windows
+winget install Rust.Rust
+
+# On Unix-like systems (https://rustup.rs/)
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+## Usage
+
+### Basic Password Hashing
+
+```elixir
+# Hash a password with default OWASP settings
+hash = Argon2.hash_password("secure_password123")
+
+# Verify a password
+if Argon2.verify_password("secure_password123", hash) do
+  # Password matches
+else
+  # Password is incorrect
+end
+```
+
+### Configuration Presets
+
+Three security presets are available:
+
+```elixir
+# OWASP (default) - Recommended for most use cases
+hash = Argon2.hash_password("secure_password123")
+
+# Strong - Higher security for sensitive applications
+hash = Argon2.hash_password("secure_password123", "strong")
+
+# Test - Fast but unsafe, only for testing purposes
+hash = Argon2.hash_password("secure_password123", "test_unsafe")
+```
+
+Preset specifications:
+- OWASP: m=19456 KiB, t=2, p=1
+- Strong: m=65540 KiB, t=3, p=4
+- Test: m=1024 KiB, t=1, p=1 (Useful for testing)
+
+### Benchmarking
+
+You can benchmark the different configurations on your hardware:
+
+```bash
+mix run -e "Argon2.Benchmark.run(10)"
+```
+
+```elixir
+Configuration Benchmarks (averaged over 10 runs):
+
+OWASP:
+  Hash time: 25ms
+  Verify time: 24ms
+  Memory: 19MB
+
+STRONG:
+  Hash time: 145ms
+  Verify time: 139ms
+  Memory: 65MB
+
+TEST_UNSAFE:
+  Hash time: 1ms
+  Verify time: 1ms
+  Memory: 1MB
+```
+
+## Development
+
+```bash
+# Install dependencies
+mix deps.get
+
+# Run tests
+mix test
+
+# Run benchmarks
+mix run -e "Argon2.Benchmark.run()"
+
+# Run code quality checks
+mix quality
+
+# Generate documentation
+mix docs
+
+# Format code
+mix format
+```
+
+
+## License
+
+Licensed under either of
+
+- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
+- MIT license ([LICENSE-MIT](LICENSE-MIT) or http://opensource.org/licenses/MIT)
+
+at your option.
+
+## Credits
+
+- [RustCrypto Argon2](https://github.com/RustCrypto/password-hashes/tree/master/argon2) - The Rust implementation
+- [Rustler](https://github.com/rusterlium/rustler) - Elixir NIF interface