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:

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

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.