sarhash 0.1.0

Fast password hashing library powered by Rust

Sarhash

Fast and secure password hashing library powered by Rust with Python bindings.

Features

• 🚀 Blazing Fast: Rust-powered performance (via sarhash-core)
• 🔒 Secure: Industry-standard strength
• 🎯 Simple API: Easy-to-use Python interface
• 💪 Type Safe: Complete type hints with .pyi stubs
• 📊 Password Strength: Built-in strength checking
• 🔄 Batch Operations: Efficient multi-password hashing

Installation

Prerequisites

• Python 3.11+
• Rust toolchain
• uv (recommended) or pip

Step-by-Step Setup

1. Install Rust

Sarhash uses Rust for its core implementation. Install Rust using rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

After installation, restart your terminal and verify:

rustc --version
cargo --version

2. Install uv

uv is a fast Python package installer and resolver.

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or using pip:

pip install uv

3. Setup Project

# Create virtual environment
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install maturin
uv pip install maturin

# Build and install
maturin develop --release

Quick Start

import sarhash

# Hash a password
hashed = sarhash.hash_password("my_secure_password")

# Verify a password
is_valid = sarhash.verify_password("my_secure_password", hashed)
print(is_valid)  # True

Tutorial

Basic Usage

Hashing a Password

Hash a password using the default strong algorithm:

import sarhash

password = "user_password_123"
hashed = sarhash.hash_password(password)

print(hashed)
# Output: $argon2id$v=19$m=19456,t=2,p=1$...

Verifying a Password

To verify a password against a stored hash:

import sarhash

# Stored hash from database
stored_hash = "$argon2id$v=19$m=19456,t=2,p=1$..."

# User input
user_input = "user_password_123"

# Verify
if sarhash.verify_password(user_input, stored_hash):
    print("Password is correct!")
else:
    print("Invalid password")

Password Strength Checking

Check password strength before hashing:

import sarhash

password = "MyP@ssw0rd2024"
strength = sarhash.check_password_strength(password)

print(f"Score: {strength.score}/4")
print(f"Is strong: {strength.is_strong}")
print(f"Feedback: {strength.feedback}")

Batch Operations

Hash multiple passwords efficiently:

import sarhash

passwords = ["user1_pass", "user2_pass", "user3_pass"]
hashes = sarhash.hash_multiple(passwords)

for pwd, hash in zip(passwords, hashes):
    print(f"{pwd} -> {hash[:50]}...")

API Reference

Core Functions

hash_password(password: str) -> str

Hash a password using the default algorithm.

Parameters:

• password (str): The password to hash

Returns:

• str: The hashed password in PHC format

Raises:

• ValueError: If password is empty or hashing fails

verify_password(password: str, hash: str) -> bool

Verify a password against a hash.

Parameters:

• password (str): The password to verify
• hash (str): The hash to verify against

Returns:

• bool: True if password matches, False otherwise

Raises:

• ValueError: If hash format is invalid

Enhanced Features

check_password_strength(password: str) -> PasswordStrength

Check password strength with detailed feedback.

Parameters:

• password (str): Password to evaluate

Returns:

• PasswordStrength: Object with score (0-4), feedback (list), and is_strong property

hash_multiple(passwords: list[str]) -> list[str]

Hash multiple passwords efficiently.

Parameters:

• passwords (list[str]): List of passwords to hash

Returns:

• list[str]: List of hashed passwords

Development

Building a Wheel Package

To build a distributable wheel package:

maturin build --release

The wheel will be created in target/wheels/.

To install the wheel:

uv pip install target/wheels/sarhash-*.whl

Development Workflow

When developing:

1. Make changes to Rust code in src/
2. Rebuild: maturin develop
3. Test your changes: python examples/basic_usage.py
4. Run type checking: mypy python/sarhash
5. Format code: black python/

Project Structure

.
├── Cargo.toml              # Rust package configuration
├── pyproject.toml          # Python package configuration
├── .python-version         # Python version for uv
├── src/
│   └── lib.rs             # Rust implementation binding to sarhash-core
├── python/
│   └── sarhash/
│       ├── __init__.py    # Python wrapper with enhanced features
│       ├── __init__.pyi   # Type stubs
│       └── py.typed       # PEP 561 marker
└── examples/
    └── basic_usage.py     # Usage examples

Security Best Practices

1. Always use the latest version - Keep sarhash updated
2. Never store plain text passwords - Always hash before storing
3. Check password strength - Use check_password_strength() before hashing
4. Use HTTPS - Always transmit passwords over encrypted connections
5. Implement rate limiting - Prevent brute-force attacks

License

MIT License - see LICENSE for details.