argon2id_elixir/README.md

# 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