csh256 1.0.6

CSH-256: A hybrid password hashing algorithm with time-cost resistance

CSH-256: Custom Secure Hash - 256 bit

A hybrid password hashing algorithm combining the structural robustness of traditional cryptographic hash functions with the time-cost resistance of key derivation functions.

Features

• 🔒 Hardware-Resistant: Designed to resist GPU/ASIC attacks through computational slowdown
• 🎯 Avalanche Effect: 51.56% bit diffusion rate (near-optimal 50%)
• ⚡ High-Performance C Core: Optional C extension for maximum speed
• 🔧 Configurable: Adjustable iteration count for future-proof security
• 🛡️ Battle-Tested Primitives: Uses SHA-256 structure, AES S-Box, and RSA-inspired operations
• 📦 Zero Dependencies: Pure Python + optional C extension

Algorithm Overview

CSH-256 implements three security layers:

1. Non-Linearity Layer: AES S-Box substitution for enhanced diffusion
2. Computational Slowdown: Modular Cubing (h³ mod 2⁶⁴)
3. Time-Cost Iteration: Password stretching through repeated compression

The algorithm achieves 51.56% avalanche effect, meaning changing a single input bit changes approximately half of the output bits.

Installation

From PyPI (Recommended)

pip install csh256

From Source (with C extension)

git clone https://github.com/hemaabokila/CSH-256-Repo.git
cd CSH-256-Repo
pip install -e .

Pure Python (no C compiler needed)

pip install csh256 --no-binary csh256

Quick Start

Basic Usage

import csh256

# Hash a password (auto-generates salt)
hash_result = csh256.hash("my_secure_password")
print(hash_result)
# Output: 'a3f2b1c4d5e6f7a8b9c0d1e2f3a4b5c6...'

Complete Example with Storage

import csh256

# Create a hash with all parameters
result = csh256.hash_full("my_secure_password")

# Store in database (PHC format)
db.store_user(username="alice", password_hash=result['formatted'])
# Stores: '$csh256$i=4096$3f4e2a1b...$a3f2b1c4...'

# Later, verify password
stored_hash = db.get_password_hash("alice")
is_valid = csh256.verify("my_secure_password", formatted=stored_hash)
print(f"Password valid: {is_valid}")

Custom Parameters

import csh256

# Use custom salt and iterations
custom_salt = csh256.generate_salt()
result = csh256.hash_full(
    "my_password",
    salt=custom_salt,
    iterations=8192  # Higher = more secure but slower
)

print(f"Hash: {result['hash']}")
print(f"Salt: {result['salt'].hex()}")
print(f"Iterations: {result['iterations']}")

API Reference

Core Functions

hash(password, salt=None, iterations=None)

Generate a CSH-256 hash (returns hex string only).

Parameters:

• password (str | bytes): Password to hash
• salt (bytes, optional): 16-byte salt (auto-generated if None)
• iterations (int, optional): Iteration count (default: 4096)

Returns: 64-character hexadecimal hash string

---

hash_full(password, salt=None, iterations=None)

Generate complete hash with all parameters.

Returns: Dictionary with keys:

• hash: Hex hash string
• salt: Salt bytes
• iterations: Iteration count
• formatted: PHC-formatted string

---

verify(password, hash_value=None, salt=None, iterations=None, formatted=None)

Verify a password against stored hash.

Parameters:

• password (str | bytes): Password to verify
• Either:
  • hash_value, salt, iterations: Individual components
  • formatted: PHC-formatted string

Returns: True if valid, False otherwise

---

Utility Functions

generate_salt(size=16)

Generate cryptographically secure random salt.

format_hash(hash_value, salt, iterations)

Format components into PHC string.

parse_hash(formatted)

Parse PHC string into components.

recommend_iterations(target_time_ms=250)

Recommend iteration count based on target computation time.

# Find iterations for ~500ms computation
iterations = csh256.recommend_iterations(500)
print(f"Use {iterations} iterations")

Performance Benchmarks

Tested on Intel i7-10700K @ 3.80GHz:

Iterations	Time (Python)	Time (C)	Speedup
1,024	0.85s	0.12s	7.1x
4,096	3.42s	0.48s	7.1x
8,192	6.84s	0.96s	7.1x
16,384	13.68s	1.92s	7.1x

Security Considerations

Recommended Iterations

• Minimum: 4,096 iterations
• Standard: 8,192 iterations (~500ms)
• High-Security: 16,384+ iterations (~1s+)

Salt Requirements

• Must be exactly 16 bytes
• Must be cryptographically random
• Must be unique per password
• Use csh256.generate_salt() for secure generation

Storage Format

Always store using PHC format:

$csh256$i=4096$<salt_hex>$<hash_hex>

This format includes all parameters needed for verification.

Algorithm Specification

Architecture

• Structure: Merkle–Damgård construction
• Block Size: 512 bits
• Output Size: 256 bits
• Rounds: 64 per compression

Security Primitives

1. SHA-256 Functions: Σ₀, Σ₁, σ₀, σ₁, CH, MAJ
2. AES S-Box: 8-bit non-linear substitution
3. RSA Primitive: Modular Cubing (h³ mod 2⁶⁴)

Avalanche Effect

• Measured: 51.56% bit diffusion
• Ideal: 50.00%
• Interpretation: Near-perfect statistical independence

Testing

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=csh256 tests/

# Run benchmarks
pytest tests/test_performance.py -v

Development

# Install development dependencies
pip install -e ".[dev]"

# Format code
black csh256/ tests/

# Type checking
mypy csh256/

# Linting
flake8 csh256/

Comparison with Other Algorithms

Algorithm	Type	Memory-Hard	GPU-Resistant	Configurable Cost
CSH-256	Hybrid	No	Yes	Yes (iterations)
Bcrypt	KDF	No	Partial	Yes (cost factor)
Scrypt	KDF	Yes	Yes	Yes (N, r, p)
Argon2	KDF	Yes	Yes	Yes (t, m, p)
PBKDF2	KDF	No	No	Yes (iterations)

CSH-256 focuses on computational cost through non-parallelizable operations rather than memory hardness.

License

MIT License - see LICENSE file for details.

Citation

If you use CSH-256 in academic work, please cite:

@software{csh256,
  author = {Aboukila, Ibrahim Hilal},
  title = {CSH-256: A Hybrid Password Hashing Algorithm},
  year = {2025},
  url = {https://github.com/hemaabokila/CSH-256-Repo}
}

Contributing

Contributions welcome! Please read CONTRIBUTING.md first.

References

1. Rivest, R. L., et al. (1978). "A Method for Obtaining Digital Signatures and Public-Key Cryptosystems"
2. NIST FIPS 180-4: Secure Hash Standard (SHS)
3. Daemen, J., & Rijmen, V. (2002). "The Design of Rijndael: AES"

Author

Ibrahim Hilal Aboukila

Acknowledgments

Special thanks to the cryptography community for their foundational work in hash functions and key derivation.

---

⚠️ Security Notice: While CSH-256 implements multiple security layers, always use the latest recommended iteration counts and follow secure password practices. For production use, conduct thorough security audits.