# Keçeci Hash Algorithm (Keçeci Hash Algoritması), KHA-256

---

# KHA-256 <img src="docs/kha256.jpg" alt="logo" align="right" height="140"/>

## KEÇECİ HASH ALGORİTMASI (KHA-256) 🇹🇷/Eng

<div align="center">

![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)
![License](https://img.shields.io/badge/license-AGPL--3.0-green)
![Version](https://img.shields.io/badge/version-0.1.2-orange)
![Status](https://img.shields.io/badge/status-production--ready-brightgreen)

[![PyPI version](https://badge.fury.io/py/kha256.svg)](https://badge.fury.io/py/kha256/)
[![License: AGPL](https://img.shields.io/badge/License-AGPL-yellow.svg)](https://opensource.org/license/agpl-v3)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18089401.svg)](https://doi.org/10.5281/zenodo.18089401)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18089401.svg)](https://doi.org/10.5281/zenodo.18156885)


[![Anaconda-Server Badge](https://anaconda.org/bilgi/kha256/badges/version.svg)](https://anaconda.org/bilgi/kha256)
[![Anaconda-Server Badge](https://anaconda.org/bilgi/kha256/badges/latest_release_date.svg)](https://anaconda.org/bilgi/kha256)
[![Anaconda-Server Badge](https://anaconda.org/bilgi/kha256/badges/platforms.svg)](https://anaconda.org/bilgi/kha256)
[![Anaconda-Server Badge](https://anaconda.org/bilgi/kha256/badges/license.svg)](https://anaconda.org/bilgi/kha256)

[![Open Source](https://img.shields.io/badge/Open%20Source-Open%20Source-brightgreen.svg)](https://opensource.org/)
[![Documentation Status](https://app.readthedocs.org/projects/kha256/badge/?0.1.0=main)](https://kha256.readthedocs.io/en/stable/)
[![OpenSSF Best Practices](https://www.bestpractices.dev/projects/11668/badge)](https://www.bestpractices.dev/projects/11668)
[![](https://badges.frapsoft.com/os/v1/open-source.png?v=103)](https://github.com/WhiteSymmetry/kha256)

[![Python CI](https://github.com/WhiteSymmetry/kha256/actions/workflows/python_ci.yml/badge.svg?branch=main)](https://github.com/WhiteSymmetry/kha256/actions/workflows/python_ci.yml)
[![codecov](https://codecov.io/gh/WhiteSymmetry/kha256/graph/badge.svg?token=DFJ046KEDT)](https://codecov.io/gh/WhiteSymmetry/kha256)
[![Documentation Status](https://readthedocs.org/projects/kha256/badge/?version=latest)](https://kha256.readthedocs.io/en/latest/)
[![Binder](https://terrarium.evidencepub.io/badge_logo.svg)](https://terrarium.evidencepub.io/v2/gh/WhiteSymmetry/kha256/HEAD)

[![PyPI version](https://badge.fury.io/py/kha256.svg)](https://badge.fury.io/py/kha256)
[![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
[![Linted with Ruff](https://img.shields.io/badge/Linted%20with-Ruff-green?logo=python&logoColor=white)](https://github.com/astral-sh/ruff)
[![Lang:Python](https://img.shields.io/badge/Lang-Python-blue?style=flat-square&logo=python)](https://python.org/)

[![PyPI Downloads](https://static.pepy.tech/badge/kha256)](https://pepy.tech/projects/kha256)
![PyPI Downloads](https://img.shields.io/pypi/dm/kha256?logo=pypi&label=PyPi%20downloads)
[![](https://data.jsdelivr.com/v1/package/gh/WhiteSymmetry/kha256/badge)](https://www.jsdelivr.com/package/gh/WhiteSymmetry/kha256)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/kha256?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=downloads)](https://pepy.tech/projects/kha256)
[![Socket Badge](https://badge.socket.dev/pypi/package/kha256/0.1.2?artifact_id=tar-gz)](https://socket.dev/pypi/package/kha256)

**Performanstan Fedakarlık Edilerek Güvenlik Maksimize Edilmiş Hash Algoritması**  
**Hash Algorithm with Security Maximized at the Sacrifice of Performance**

</div>

---

## 📖 İçindekiler / Table of Contents
- [🇹🇷 Türkçe](#türkçe)
  - [Özellikler](#özellikler)
  - [Kurulum](#kurulum)
  - [Hızlı Başlangıç](#hızlı-başlangıç)
  - [Detaylı Kullanım](#detaylı-kullanım)
  - [Güvenlik Testleri](#güvenlik-testleri)
  - [Performans](#performans)
  - [API Referansı](#api-referansı)
  - [Katkıda Bulunma](#katkıda-bulunma)
  - [Lisans](#lisans)
- [English](#english)
  - [Features](#features)
  - [Installation](#installation)
  - [Quick Start](#quick-start)
  - [Advanced Usage](#advanced-usage)
  - [Security Tests](#security-tests)
  - [Performance](#performance)
  - [API Reference](#api-reference)
  - [Contributing](#contributing)
  - [License](#license)

---

# 🇹🇷 Türkçe

## 🚀 Özellikler

### 🔐 Güvenlik Öncelikli
- **256-bit hash çıktısı** - Endüstri standardı
- **Güçlü Avalanche Etkisi** - %49.5-50.5 ideal aralık
- **Kuantum Dirençli Tasarım** - Post-kuantum güvenlik
- **Çoklu Keçeci Sayısı Türleri** - 23 farklı matematiksel sistem
- **Entropi İnjeksiyonu** - Zaman ve sistem bazlı entropy
- **Çift Hashleme** - Ek güvenlik katmanı
- **Memory-Hard** - TrueMemoryHardHasher, MemoryHardHash, MemoryHardEngine, FortifiedKhaHash256

### ⚡ Performans Optimizasyonları
- **Vektörel İşlemler** - NumPy ile optimize edilmiş
- **Akıllı Önbellekleme** - Tekrarlanan işlemler için
- **Batch İşleme** - Toplu hash işlemleri için optimize
- **Paralel İşleme Hazır** - (Opsiyonel)

### 🧪 Kapsamlı Testler
- **Avalanche Testi** - Bit değişim analizi
- **Çakışma Testi** - Hash çakışmalarının önlenmesi
- **Uniformluk Testi** - Bit dağılım analizi
- **Performans Benchmark** - Hız ve verimlilik testleri

## 📦 Kurulum

### Gereksinimler
- Python 3.11 veya üzeri
- NumPy 2.3.0+
- KeçeciNumbers 0.8.4+

### Pip ile Kurulum
```bash
pip install -U kha256==0.8.4
pip install -U numpy>=2.3.0
```

### Manuel Kurulum
```bash
# Repository'yi klonla
git clone https://github.com/WhiteSymmetry/kha256.git
cd kha256

# Bağımlılıkları yükle
pip install -r requirements.txt

# Geliştirici modunda yükle
pip install -e .
```

## 🎯 Hızlı Başlangıç

### Temel Hashleme
```python
from kha256 import quick_hash

# Basit metin hash'i
hash_result = quick_hash("Merhaba Dünya!")
print(f"Hash: {hash_result}")
# Örnek: 8f3a2b1c5d7e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5
```

### Şifre Hashleme
```python
from kha256 import hash_password
import os

#  minimum 16 byte salt gereksinim
salt = secrets.token_bytes(64)  # 64 byte
print(salt)

password = b"GizliSifre123!" # sadece byte
hashed_password = hash_password(password, salt)
print(f"Hashlenmiş Şifre: {hashed_password[:80]}...")
```

### Komut Satırı Kullanımı
```bash
# Test çalıştır
python -m kha256 --test

# Tek hash oluştur
python -m kha256 --hash "Merhaba Dünya!"

# Performans testi
python -m kha256 --benchmark

# Demo modu
python -m kha256 --demo
```

## 🔧 Detaylı Kullanım

### Özelleştirilmiş Hasher
```python
from kha256 import FortifiedKhaHash256, FortifiedConfig

# Özel konfigürasyon
config = FortifiedConfig(
    iterations=20,           # Daha fazla iterasyon
    shuffle_layers=16,       # Daha fazla karıştırma katmanı
    salt_length=64,         # Daha uzun tuz
    double_hashing=True,     # Çift hashleme aktif
    #enable_quantum_resistance=True  # Kuantum direnç
)

# Hasher oluştur
hasher = FortifiedKhaHash256(config)

# Veriyi hash'le
data = "Önemli gizli veri"
salt = secrets.token_bytes(64)  # Güçlü tuz
hash_result = hasher.hash(data, salt)

print(f"Hash: {hash_result}")
```

### Batch İşlemleri
```python
from kha256 import FortifiedKhaHash256

hasher = FortifiedKhaHash256()

# Çoklu veri hash'leme
data_list = ["veri1", "veri2", "veri3", "veri4"]
hashes = [hasher.hash(data) for data in data_list]

# Dosya hash'leme
def hash_file(file_path):
    with open(file_path, 'rb') as f:
        file_data = f.read()
    return hasher.hash(file_data)
```

## 🛡️ Güvenlik Testleri

### Avalanche Testi
```python
from kha256 import FortifiedKhaHash256

hasher = FortifiedKhaHash256()
results = hasher.test_avalanche_effect(samples=100)

print(f"Ortalama Bit Değişimi: {results['avg_bit_change_percent']:.2f}%")
print(f"İdeal Aralıkta: {results['in_ideal_range']}")
print(f"Durum: {results['status']}")
# Çıktı: EXCELLENT, GOOD, ACCEPTABLE veya POOR
```

### Çakışma Testi
```python
results = hasher.test_collision_resistance(samples=5000)
print(f"Çakışma Sayısı: {results['collisions']}")
print(f"Çakışma Oranı: {results['collision_rate_percent']:.6f}%")
```

### Kapsamlı Test
```python
from kha256 import run_comprehensive_test

# Tüm testleri çalıştır
hasher = run_comprehensive_test()
```

## 📊 Performans

### Benchmark Sonuçları
```
Boyut     Ortalama Süre    Verim
------    -------------    ------
64 byte     ? ms        ? MB/s
256 byte    ? ms        ? MB/s
1 KB        ? ms        ? MB/s
4 KB        ? ms        ? MB/s
16 KB       ? ms        ? MB/s
```

### Performans Optimizasyonları
```python
from kha256 import FortifiedConfig

# Hızlı mod (daha az güvenlik, daha hızlı)
fast_config = FortifiedConfig(
    iterations=8,
    shuffle_layers=6,
    components_per_hash=12,
    #enable_quantum_resistance=False,
    double_hashing=False
)

# Güvenlik mod (maksimum güvenlik)
secure_config = FortifiedConfig(
    iterations=24,
    shuffle_layers=20,
    components_per_hash=32,
    #enable_quantum_resistance=True,
    double_hashing=True,
    triple_compression=True
)
```

## 📚 API Referansı

### Ana Sınıflar

#### `FortifiedKhaHash256`
Ana hash sınıfı.

```python
class FortifiedKhaHash256:
    def __init__(self, config: Optional[FortifiedConfig] = None):
    def hash(self, data: Union[str, bytes], salt: Optional[bytes] = None) -> str:
    def test_avalanche_effect(self, samples: int = 100) -> Dict[str, Any]:
    def test_collision_resistance(self, samples: int = 5000) -> Dict[str, Any]:
    def test_uniformity(self, samples: int = 5000) -> Dict[str, Any]:
    def get_stats(self) -> Dict[str, Any]:
```

#### `FortifiedConfig`
# Her sürümde bu yapılanma değişmektedir ve sabit değildir.
# The structure of this organization changes with each version and is not fixed.

Konfigürasyon sınıfı.

```python
# Buradaki değerler sabit olmayıp her sürümde değişmektedir
@dataclass
class FortifiedConfig:
    output_bits: int = 256
    hash_bytes: int = 32
    iterations: int = 16
    rounds: int = 8
    components_per_hash: int = 20
    salt_length: int = 96
    shuffle_layers: int = 12
    diffusion_rounds: int = 9
    avalanche_boosts: int = 6
    enable_quantum_resistance: bool = True
    enable_post_quantum_mixing: bool = True
    double_hashing: bool = True
    triple_compression: bool = True
    memory_hardening: bool = False # memory-hard: TrueMemoryHardHasher, MemoryHardHash, MemoryHardEngine, FortifiedKhaHash256
    entropy_injection: bool = True
    time_varying_salt: bool = True
    context_sensitive_mixing: bool = True
    cache_enabled: bool = False
    parallel_processing: bool = False
```

### Yardımcı Fonksiyonlar

```python
# Hızlı hash
quick_hash(data: Union[str, bytes]) -> str

# Şifre hashleme
hash_password(password: str, salt: Optional[bytes] = None) -> str

# Hasher oluşturma
generate_fortified_hasher() -> FortifiedKhaHash256

# Test çalıştırma
run_comprehensive_test() -> FortifiedKhaHash256

# Benchmark
benchmark_hash(data_sizes: List[int] = [64, 256, 1024, 4096]) -> Dict[str, Any]
```

### Geliştirme Ortamı Kurulumu
```bash
# Repository'yi klonla
git clone https://github.com/mehmetkececi/kha256.git
cd kha256

# Sanal ortam oluştur
python -m venv venv
source venv/bin/activate  # Linux/Mac
# veya
venv\Scripts\activate  # Windows

# Bağımlılıkları yükle
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Geliştirme bağımlılıkları

# Testleri çalıştır
pytest tests/
python -m kha256 --test
```

### Kod Standartları
- [PEP 8](https://www.python.org/dev/peps/pep-0008/) stil rehberi
- Type hint'ler kullanılmalı
- Docstring'ler yazılmalı
- Unit testler eklenmeli

## 📄 Lisans

Bu proje AGPL-3.0-or-later lisansı altında lisanslanmıştır. Detaylar için [LICENSE](LICENSE) dosyasına bakın.

```
Copyright 2025 Mehmet Keçeci

Bu program özgür yazılımdır: Özgür Yazılım Vakfı tarafından yayınlanan
GNU Affero Genel Kamu Lisansı’nın 3. ya da (isteğinize bağlı olarak) daha
sonraki sürümlerinin koşulları altında yeniden dağıtabilir ve/veya
değiştirebilirsiniz.

Bu program, yararlı olması umuduyla dağıtılmış olup, hiçbir garantisi yoktur;
hatta SATILABİLİRLİĞİ veya ŞAHİSİ BİR AMACA UYGUNLUĞU için dahi garanti
vermez. Daha fazla ayrıntı için GNU Affero Genel Kamu Lisansı’na bakınız.

Bu programla birlikte GNU Affero Genel Kamu Lisansı’nın bir kopyasını
almış olmalısınız. Almadıysanız, <http://www.gnu.org/licenses/> adresine bakınız.
```

---

# English

## 🚀 Features

### 🔐 Security First
- **256-bit hash output** - Industry standard
- **Strong Avalanche Effect** - 49.5-50.5% ideal range
- **Quantum-Resistant Design** - Post-quantum security
- **Multiple Keçeci Number Types** - 22 different mathematical systems
- **Entropy Injection** - Time and system-based entropy
- **Double Hashing** - Additional security layer

### ⚡ Performance Optimizations
- **Vectorized Operations** - Optimized with NumPy
- **Smart Caching** - For repeated operations
- **Batch Processing** - Optimized for bulk hashing
- **Parallel Processing Ready** - (Optional)

### 🧪 Comprehensive Tests
- **Avalanche Test** - Bit change analysis
- **Collision Test** - Hash collision prevention
- **Uniformity Test** - Bit distribution analysis
- **Performance Benchmark** - Speed and efficiency tests

## 📦 Installation

### Requirements
- Python 3.10 or higher
- NumPy 2.20.0+
- KeçeciNumbers 0.8.4+

### Install via Pip
```bash
pip install kha256==0.8.4
pip install numpy>=1.20.0
```

### Manual Installation
```bash
# Clone repository
git clone https://github.com/WhiteSymmetry/kha256.git
cd kha256

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .
```

## 🎯 Quick Start

### Basic Hashing
```python
from kha256 import quick_hash

# Simple text hash
hash_result = quick_hash("Hello World!")
print(f"Hash: {hash_result}")
# Example: 8f3a2b1c5d7e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5
```

### Password Hashing
```python
from kha256 import hash_password

password = "SecretPassword123!"
hashed_password = hash_password(password)
print(f"Hashed Password: {hashed_password[:80]}...")
```

### Command Line Usage
```bash
# Run tests
python -m kha256 --test

# Create single hash
python -m kha256 --hash "Hello World!"

# Performance test
python -m kha256 --benchmark

# Demo mode
python -m kha256 --demo
```

## 🔧 Advanced Usage

### Customized Hasher
```python
from kha256 import FortifiedKhaHash256, FortifiedConfig

# Custom configuration
config = FortifiedConfig(
    iterations=20,           # More iterations
    shuffle_layers=16,       # More mixing layers
    salt_length=128,         # Longer salt
    double_hashing=True,     # Double hashing active
    enable_quantum_resistance=True  # Quantum resistance
)

# Create hasher
hasher = FortifiedKhaHash256(config)

# Hash data
data = "Important secret data"
salt = secrets.token_bytes(64)  # Strong salt
hash_result = hasher.hash(data, salt)

print(f"Hash: {hash_result}")
```

### Batch Operations
```python
from kha256 import FortifiedKhaHash256

hasher = FortifiedKhaHash256()

# Multiple data hashing
data_list = ["data1", "data2", "data3", "data4"]
hashes = [hasher.hash(data) for data in data_list]

# File hashing
def hash_file(file_path):
    with open(file_path, 'rb') as f:
        file_data = f.read()
    return hasher.hash(file_data)
```

## 🛡️ Security Tests

### Avalanche Test
```python
from kha256 import FortifiedKhaHash256

hasher = FortifiedKhaHash256()
results = hasher.test_avalanche_effect(samples=100)

print(f"Average Bit Change: {results['avg_bit_change_percent']:.2f}%")
print(f"In Ideal Range: {results['in_ideal_range']}")
print(f"Status: {results['status']}")
# Output: EXCELLENT, GOOD, ACCEPTABLE or POOR
```

### Collision Test
```python
results = hasher.test_collision_resistance(samples=5000)
print(f"Collisions: {results['collisions']}")
print(f"Collision Rate: {results['collision_rate_percent']:.6f}%")
```

### Comprehensive Test
```python
from kha256 import run_comprehensive_test

# Run all tests
hasher = run_comprehensive_test()
```

## 📊 Performance

### Benchmark Results
```
Size      Average Time    Throughput
------    -------------    ----------
64 byte     ? ms        ? MB/s
256 byte    ? ms        ? MB/s
1 KB        ? ms        ? MB/s
4 KB        ? ms        ? MB/s
16 KB       ? ms        ? MB/s
```

### Performance Optimizations
```python
from kha256 import FortifiedConfig

# Fast mode (less security, faster)
fast_config = FortifiedConfig(
    iterations=8,
    shuffle_layers=6,
    components_per_hash=12,
    enable_quantum_resistance=False,
    double_hashing=False
)

# Security mode (maximum security)
secure_config = FortifiedConfig(
    iterations=24,
    shuffle_layers=20,
    components_per_hash=32,
    enable_quantum_resistance=True,
    double_hashing=True,
    triple_compression=True
)
```

## 📚 API Reference

### Main Classes

#### `FortifiedKhaHash256`
Main hash class.

```python
class FortifiedKhaHash256:
    def __init__(self, config: Optional[FortifiedConfig] = None)
    def hash(self, data: Union[str, bytes], salt: Optional[bytes] = None) -> str
    def test_avalanche_effect(self, samples: int = 100) -> Dict[str, Any]
    def test_collision_resistance(self, samples: int = 5000) -> Dict[str, Any]
    def test_uniformity(self, samples: int = 5000) -> Dict[str, Any]
    def get_stats(self) -> Dict[str, Any]
```

#### `FortifiedConfig`
Configuration class.

```python
@dataclass
class FortifiedConfig:
    output_bits: int = 256
    hash_bytes: int = 32
    iterations: int = 16
    rounds: int = 8
    components_per_hash: int = 20
    salt_length: int = 96
    shuffle_layers: int = 12
    diffusion_rounds: int = 9
    avalanche_boosts: int = 6
    enable_quantum_resistance: bool = True
    enable_post_quantum_mixing: bool = True
    double_hashing: bool = True
    triple_compression: bool = True
    memory_hardening: bool = True
    entropy_injection: bool = True
    time_varying_salt: bool = True
    context_sensitive_mixing: bool = True
    cache_enabled: bool = False
    parallel_processing: bool = False
```

### Helper Functions

```python
# Quick hash
quick_hash(data: Union[str, bytes]) -> str

# Password hashing
hash_password(password: str, salt: Optional[bytes] = None) -> str

# Hasher creation
generate_fortified_hasher() -> FortifiedKhaHash256

# Run tests
run_comprehensive_test() -> FortifiedKhaHash256

# Benchmark
benchmark_hash(data_sizes: List[int] = [64, 256, 1024, 4096]) -> Dict[str, Any]

[![memory-hard](https://github.com/WhiteSymmetry/kha256/blob/main/notebooks/kha256_demo.ipynb)](https://github.com/WhiteSymmetry/kha256/blob/main/notebooks/kha256_demo.ipynb)
```

### Development Environment Setup
```bash
# Clone repository
git clone https://github.com/mehmetkececi/kha256.git
cd kha256

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or
venv\Scripts\activate  # Windows

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt  # Development dependencies

# Run tests
pytest tests/
python -m kha256 --test
```

### Code Standards
- Follow [PEP 8](https://www.python.org/dev/peps/pep-0008/) style guide
- Use type hints
- Write docstrings
- Add unit tests

## 📄 License

This project is licensed under the AGPL-3.0 License. See the [LICENSE](LICENSE) file for details.

```
Copyright 2025 Mehmet Keçeci

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published
by the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program. If not, see <http://www.gnu.org/licenses/>.
```

### APA

```

Keçeci, M. (2025). KHA-256: A Next-Generation Cryptographic Hash Function Based on Keçeci Numbers and Mathematical Constants. Open Science Articles (OSAs), Zenodo. https://doi.org/10.5281/zenodo.18156885

Keçeci, M. (2025). KHA-256. GitHub, PyPI, Anaconda, Zenodo. https://doi.org/10.5281/zenodo.18089401 & https://github.com/WhiteSymmetry/kha256 & https://pypi.org/project/kha256 & https://anaconda.org/bilgi/kha256

Keçeci, M. (2025). Keçeci Hash Algorithm (Keçeci Hash Algoritması), KHA-256. https://github.com/WhiteSymmetry/kha256

Keçeci, M. (2025). Keçeci Hash Algorithm (Keçeci Hash Algoritması), KHA-256. https://pypi.org/project/kha256

Keçeci, M. (2025). Keçeci Hash Algorithm (Keçeci Hash Algoritması), KHA-256. https://anaconda.org/channels/bilgi/packages/kha256/overview

Keçeci, M. (2025). Keçeci Hash Algorithm (Keçeci Hash Algoritması), KHA-256. Zenodo. https://doi.org/10.5281/zenodo.18089401

---

```
KHA-256 v0.1.1
==========================================

## 🚀 ÖZELLİKLER
- NIST SP 800-90B/22 uyumlu güvenlik
- Mükemmel avalanche etkisi (%90 ideal)
- Yüksek performans: 0.02ms/hash, 35+ MB/s throughput
- Etkili cache mekanizması: %100 hit rate
- Kuantum direnci ve post-kuantum karıştırma
- Çift hash ile güçlü çakışma direnci

## 📊 PERFORMANS
- Ortalama hash süresi: 0.02ms (cached)
- Throughput: 35,597 KB/s
- SHA-256 karşılaştırması: 25.3x daha yavaş (güvenlik özellikleri nedeniyle)

## ✅ TEST SONUÇLARI
- Genel Puan: 98.4/100 (EXCELLENT)
- Tüm güvenlik testleri geçildi
- Tüm fonksiyonel testler başarılı
- Tüm edge case'ler destekleniyor

## 🎯 KULLANIM ALANLARI
- Yüksek güvenlik gerektiren uygulamalar
- Parola hash'leme sistemleri
- Kriptografik imzalar
- Kuantum sonrası dönem için hazırlık
```


```
# Pixi:

[![Pixi](https://img.shields.io/badge/Pixi-Pixi-brightgreen.svg)](https://prefix.dev/channels/bilgi)

pixi init kha256

cd kha256

pixi workspace channel add https://prefix.dev/channels/bilgi --prepend

✔ Added https://prefix.dev/channels/bilgi

pixi add kha256

✔ Added kha256

pixi install

pixi shell

pixi run python -c "import kha256; print(kha256.__version__)"

### Çıktı:

pixi remove kha256

conda install -c https://prefix.dev/channels/bilgi kha256

pixi run python -c "import kha256; print(kha256.__version__)"

### Çıktı:

pixi run pip list | grep kha256

### kha256

pixi run pip show kha256

Name: kha256

Version: 0.9.1

Summary: KHA-256

Home-page: https://github.com/WhiteSymmetry/kha256

Author: Mehmet Keçeci

Author-email: Mehmet Keçeci <...>

License: GNU AFFERO GENERAL PUBLIC LICENSE

Copyright (c) 2025-2026 Mehmet Keçeci

```


```

# 🔐 Memory-Hard Hash Nedir? (What is Memory-Hard Hash?)


## Hazırlayan: Mehmet Keçeci

## 📚 Tanım (Definition)

**Memory-hard hash fonksiyonları**, özellikle paralel donanım saldırılarına (GPU/ASIC) karşı koruma sağlamak için tasarlanmış kriptografik fonksiyonlardır. Bu fonksiyonların temel özelliği, hesaplama süresinin **büyük miktarda belleğe erişim gerektirmesi** ve bu belleğin paralel olarak azaltılamamasıdır.

**Memory-hard hash functions** are cryptographic functions designed to provide protection against parallel hardware attacks (GPU/ASIC). Their key characteristic is that computation time **requires access to large amounts of memory**, and this memory cannot be reduced through parallelism.

## 🎯 Neden Önemli? (Why is it Important?)

### Saldırı Senaryoları (Attack Scenarios):
- **GPU Saldırıları**: Bir GPU, saniyede milyarlarca hash hesaplayabilir
- **ASIC Saldırıları**: Özel donanım, hash hesaplamayı 1000x hızlandırabilir
- **Rainbow Table Saldırıları**: Önceden hesaplanmış hash tabloları

### Koruma (Protection):
Memory-hard hash'ler bu saldırıları ekonomik olarak **pratik olmayan** hale getirir çünkü:
- Her hash için büyük bellek gerektirir (8MB+)
- Bellek erişimi sıralıdır, paralelleştirilemez
- Maliyet/yarar oranı saldırganın lehine değildir

## 🏆 KHA-256'da Memory-Hard Kullanımı

### ⚠️ ÖNEMLİ UYARI (IMPORTANT WARNING):
KHA-256'da **sadece `TrueMemoryHardHasher` gerçek memory-hard'tır!** Diğer tüm hash'ler (FortifiedKhaHash256, OptimizedKhaHash256 vb.) **memory-hard DEĞİLDİR**.

### ✅ Doğru Kullanım (Correct Usage):

🎯 Kullanım Alanları (Use Cases)
✅ Memory-Hard KULLANILMALI (Use Memory-Hard):

    Parola Depolama (Password Storage)
    Kriptografik Anahtar Türetme (Cryptographic Key Derivation)
    Çok Kritik Kimlik Doğrulama (Critical Authentication)
    Yüksek Değerli Veri Koruma (High-Value Data Protection)

❌ Memory-Hard KULLANILMAMALI (Don't Use Memory-Hard):

    Dosya Checksum/Doğrulama (File Checksum/Verification)
    Session Token'ları (Session Tokens)
    API İstek Doğrulama (API Request Validation)
    Büyük Veri Akışları (Large Data Streams)

📚 ÖĞRENİLENLER:
   • Memory-hard hash'ler GPU/ASIC saldırılarına karşı korur
   • KHA-256'da sadece TrueMemoryHardHasher kullanılmalı
   • Güvenlik ve performans arasında denge vardır
   • Doğru aracı doğru yerde kullanmak önemlidir

🔗 Gerçek KHA-256 kullanımı:
   from kha256 import TrueMemoryHardHasher
   hasher = TrueMemoryHardHasher(memory_cost_kb=8192, time_cost=3)

📈 Performans/Güvenlik Dengesi

Önemli Not: Güvenlik ve performans arasında bir denge (trade-off) vardır. Bu şu anlama gelir:

    Daha yüksek güvenlik → Daha yavaş performans
    Daha hızlı performans → Daha düşük güvenlik

Memory-hard hash'ler bu dengenin güvenlik tarafında yer alır.
Gereksinim (Requirement) 	Önerilen Hasher (Recommended Hasher) 	Süre (Time) 	Bellek (Memory) 	Güvenlik Seviyesi
Parola Depolama (Password Storage) 	TrueMemoryHardHasher 	580ms 	8MB 	🔴 YÜKSEK

*Config ile memory-hard fakat gerçek memory-hard DEĞİL

🎯 SON SÖZ (FINAL WORD)

Memory-hard hash'ler GPU/ASIC saldırılarına karşı en iyi savunmadır. KHA-256'da bu korumayı elde etmek için yalnızca TrueMemoryHardHasher kullanın. Diğer tüm hash fonksiyonları performans için optimize edilmiştir ve memory-hard DEĞİLDİR.

Unutmayın: Güvenlik ve performans arasında bir denge vardır.

    Kritik veriler (parolalar, anahtarlar) için → Güvenliği tercih edin (TrueMemoryHardHasher)
    Performans kritik uygulamalar (dosya doğrulama, API) için → Hızı tercih edin (Optimized/Hybrid hash'ler)

Doğru aracı doğru yerde kullanmak, hem güvenli hem de verimli sistemler oluşturmanın anahtarıdır.

Memory-hard hashes are the best defense against GPU/ASIC attacks. In KHA-256, to obtain this protection use only TrueMemoryHardHasher. All other hash functions are optimized for performance and are NOT memory-hard.

Remember: There is a balance between security and performance.

    For critical data (passwords, keys) → Choose security (TrueMemoryHardHasher)
    For performance-critical applications (file verification, API) → Choose speed (Optimized/Hybrid hashes)

Using the right tool in the right place is the key to building both secure and efficient systems.


Örnek kullanım/sample usage:

[![memory-hard](https://github.com/WhiteSymmetry/kha256/blob/main/notebooks/memory-hard.ipynb)](https://github.com/WhiteSymmetry/kha256/blob/main/notebooks/memory-hard.ipynb)

```

```

# 📊 KHA-256 MEMORY-HARD KARŞILAŞTIRMA TABLOSU

| Özellik | **MemoryHardHash** | **TrueMemoryHardHasher** | **MemoryHardEngine** | **FortifiedKhaHash256** |
|----------|---------------------|--------------------------|----------------------|--------------------------|
| **🧠 Tür** | Pure Python Balloon | Optimized Balloon | Engine Wrapper | Fortified Wrapper |
| **⚡ Hız (1MB)** | ~2.500 ms | ~70 ms | ~6.000 ms | ~70 ms |
| **📈 Scaling** | **2.00x** (PERFECT) | 2.05x | 1.99x | 2.03x |
| **🐍 Python** | ✅ Pure Python | ⚠️ Mixed | ✅ Pure Python | ⚠️ Mixed |
| **🔧 Bağımlılık** | Yok | C uzantıları | Yok | C uzantıları |
| **🎯 Orijinallik** | **%100 ORİJİNAL** | Balloon tabanlı | BLAKE2b tabanlı | Balloon wrapper |
| **📦 Kullanım** | `MemoryHardHash(mb).hash(data, salt)` | `TrueMemoryHardHasher(memory_cost_kb=1024)` | `MemoryHardEngine(memory_mb=1).hash(data, salt)` | `FortifiedKhaHash256(config)` |
| **🔄 Deterministik** | ✅ Evet | ✅ Evet | ✅ Evet | ✅ Evet |
| **💾 Cache** | ❌ Yok | ❌ Yok | ❌ Yok | ⚠️ Varsayılan AÇIK |
| **🔬 Avalanche** | %49.6 | %49.6 | %49.6 | %49.6 |
| **🎨 Tasarım** | Matematiksel irrasyoneller | Balloon hash | BLAKE2b varyantı | Balloon wrapper |
| **📚 Kod Satırı** | ~350 | ~200 | ~150 | ~100 |
| **⚙️ Memory-hard Tipi** | Balloon (tam) | Balloon (optimize) | Blake2b-based | Balloon (wrapper) |

---

## 📝 **DETAYLI AÇIKLAMA**

### 🥇 **MemoryHardHash** (PURE PYTHON - %100 ORİJİNAL)
```python
from kha256 import MemoryHardHash

hasher = MemoryHardHash(memory_mb=1)
hash_value = hasher.hash(b"password", salt)
```
- **✅ Tamamen pure Python** (C uzantısı yok)
- **✅ %100 orijinal matematiksel tasarım**
- **✅ Perfect scaling: 2.00x** (1MB→2MB→4MB)
- **✅ Hiçbir standart hash'ten kod alınmamıştır**
- **✅ Tüm sabitler matematiksel irrasyonellerden üretilmiştir**
- **✅ Her ortamda çalışır** (Jupyter, Web, Embedded)

### 🥈 **TrueMemoryHardHasher** (OPTIMIZE)
```python
from kha256 import TrueMemoryHardHasher

hasher = TrueMemoryHardHasher(memory_cost_kb=1024, time_cost=3)
hash_value = hasher.hash(b"password", salt)
```
- ⚠️ C uzantıları ile optimize edilmiş
- 🏎️ En hızlı memory-hard (70ms)
- 🔧 Balloon hash implementasyonu

### 🥉 **MemoryHardEngine** (ENGINE)
```python
from kha256 import MemoryHardEngine

engine = MemoryHardEngine(memory_mb=1)
hash_value = engine.hash(b"password", salt)
```
- ✅ Pure Python
- 🔧 BLAKE2b tabanlı varyant
- 🐢 En yavaş (~6000ms) - güvenli!

### 🏅 **FortifiedKhaHash256** (WRAPPER)
```python
from kha256 import FortifiedKhaHash256, FortifiedConfig

config = FortifiedConfig(enable_memory_hard_mode=True, memory_cost_kb=1024)
hasher = FortifiedKhaHash256(config)
hash_value = hasher.hash(b"password", salt)
```
- ⚠️ TrueMemoryHardHasher wrapper
- ⚠️ Cache varsayılan AÇIK! (kapatmak için `cache_enabled=False`)
- 🔧 Çok yönlü konfigürasyon

---

## 🎯 **HANGİSİNİ SEÇMELİ?**

| İhtiyaç | Önerilen | Neden |
|---------|----------|-------|
| **🔬 Araştırma/Geliştirme** | `MemoryHardHash` | Pure Python, her yerde çalışır |
| **⚡ Performans** | `TrueMemoryHardHasher` | En hızlı (~70ms) |
| **🔐 Maksimum Güvenlik** | `MemoryHardEngine` | En yavaş, brute-force dayanıklı |
| **🛡️ Fortified Sistem** | `FortifiedKhaHash256` | Esnek konfigürasyon |

---

## 📈 **PERFORMANS KARŞILAŞTIRMASI**

```
Sınıf               1MB        2MB        4MB        Scaling
------------------  ---------- ---------- ----------  --------
MemoryHardHash      2.561ms    5.131ms    10.247ms    2.00x  🥇 PERFECT!
TrueMemoryHardHasher   70ms      146ms       302ms    2.05x  🏎️ FAST
MemoryHardEngine    6.005ms   11.949ms   23.898ms*   1.99x  🐢 SLOW
FortifiedKhaHash256   72ms      151ms       307ms    2.03x  🔧 WRAPPER
*extrapolated
```

---

## 🔬 **BENZERLİKLER**

✅ Hepsi memory-hard (Balloon veya türevi)  
✅ Hepsi deterministic (aynı salt → aynı hash)  
✅ Hepsi avalanche etkisi gösterir (~%50)  
✅ Hepsi 256-bit (64 karakter hex) output  
✅ Hepsi salt zorunluluğu var  

## 🔬 **FARKLAR**

| Alan | MemoryHardHash | Diğerleri |
|------|----------------|-----------|
| **Dil** | Pure Python | C optimizasyonlu |
| **Hız** | Orta (2500ms) | Hızlı (70ms) veya Yavaş (6000ms) |
| **Orijinallik** | **%100 ORİJİNAL** | Standartlardan uyarlama |
| **Taşınabilirlik** | Mükemmel | Platform bağımlı |

---

## 🏆 **ÖZET**

**MemoryHardHash** KHA-256 ailesinin **en orijinal**, **en saf** ve **en taşınabilir** üyesidir. Hiçbir standart hash fonksiyonundan kod almamış, tamamen matematiksel irrasyonellerden üretilmiş sabitlerle çalışan **%100 özgün** bir memory-hard hash implementasyonudur.

> *"Gerçek memory-hard, saf Python, tamamen orijinal."*

```
