seigr-toolset-crypto 0.3.0

Post-classical cryptographic engine with adaptive security and entropy health monitoring

Seigr Toolset Crypto (STC)

Post-classical cryptographic engine with adaptive security and transparency

Overview

STC v0.3.0 is a research-grade cryptographic system that rejects traditional symmetric/asymmetric paradigms. Instead of XOR-based mixing, static keys, and classical block ciphers, it implements:

• Continuous Entropy Lattice (CEL) - Self-evolving entropy field with health monitoring
• Probabilistic Hashing Engine (PHE) - Multi-path hashing with adaptive difficulty scaling
• Contextual Key Emergence (CKE) - Ephemeral keys reconstructed from context intersections
• Data-State Folding (DSF) - Encryption via multidimensional tensor folding
• Polymorphic Cryptographic Flow (PCF) - Context-adaptive algorithmic morphing
• Enhanced Decoy Polymorphism - Variable-size decoy vectors with timing randomization
• State Management - Encrypted persistence with plausible deniability

Architecture

core/
├── cel/    # Continuous Entropy Lattice
├── phe/    # Probabilistic Hashing Engine
├── cke/    # Contextual Key Emergence
├── dsf/    # Data-State Folding
├── pcf/    # Polymorphic Cryptographic Flow
└── state/  # State persistence and reconstruction

interfaces/
├── api/    # Programmatic interface
├── cli/    # Command-line tools
└── bindings/  # Future cross-language bindings

utils/      # Mathematical primitives + TLV varint encoding
tests/      # Validation and integrity checks

⚡ Performance (v0.3.0)

SECURITY-FIRST with OPTIMIZED PERFORMANCE

• Default Settings (3 decoys, polymorphic features enabled):

  • Encryption: ~1.8s for small messages
  • Metadata: ~486 KB (with full security)
  • Security: FULL plausible deniability + polymorphic obfuscation

• Paranoid Mode (all features enabled):

  • Encryption: ~2.5s
  • Metadata: ~750 KB
  • Security: MAXIMUM (timing randomization, noise padding)

• Performance Mode (explicit use_decoys=False):

  • Encryption: ~0.6s
  • Metadata: ~276 KB
  • Security: REDUCED (not recommended for production)

Design Philosophy: Security features enabled by default. Performance achieved through intelligent optimization (smaller decoy lattices), NOT by disabling security.

Version History:

• v0.3.0: Security-first with 2.9x optimized performance (smaller decoy lattices)
• v0.2.1: 1.95x faster than v0.2.0, 65% smaller metadata via varint encoding
• v0.2.0: 76x faster than v0.1.0 via systematic optimizations

See docs/PERFORMANCE.md for optimization details and CHANGELOG.md for version history.

Installation

From PyPI (Recommended)

pip install seigr-toolset-crypto==0.3.0

From GitHub Release

Download the latest release from Releases:

# Install from wheel (recommended)
pip install seigr_toolset_crypto-0.2.1-py3-none-any.whl

# Or install from source tarball
pip install seigr_toolset_crypto-0.2.1.tar.gz

From Source (Development)

git clone https://github.com/Seigr-lab/SeigrToolsetCrypto.git
cd SeigrToolsetCrypto
pip install -e .

Requirements

• Python 3.9+
• NumPy 1.24.0+

Quick Start

Secure Encryption with v0.3.0 Features

from interfaces.api.stc_api import STCContext

# Initialize context with seed
ctx = STCContext('my-unique-seed')

# Encrypt with default security (decoys ENABLED, polymorphic features ON)
encrypted, metadata = ctx.encrypt(
    "Secret message",
    password="strong_password"
    # Defaults: use_decoys=True, num_decoys=3, variable_decoy_sizes=True
)

# Decrypt with same password
decrypted = ctx.decrypt(encrypted, metadata, password="strong_password")
print(decrypted)  # "Secret message"

Entropy Health Monitoring (v0.3.0)

# Check encryption quality before encrypting
profile = ctx.get_entropy_profile()
print(f"Quality: {profile['quality_score']:.2f}")  # 0.0-1.0
print(f"Status: {profile['status']}")  # EXCELLENT, GOOD, ACCEPTABLE, WEAK

# Set minimum threshold (auto-reject weak entropy)
ctx.set_minimum_entropy_threshold(0.7)  # Balanced security

# This will raise ValueError if entropy too low
encrypted, metadata = ctx.encrypt("sensitive data", password="secret")

Paranoid Mode (Maximum Security)

# Enable ALL security features
encrypted, metadata = ctx.encrypt(
    "Top secret",
    password="ultra_secure_password",
    num_decoys=5,  # More decoys
    timing_randomization=True,  # Add timing jitter
    noise_padding=True  # Add noise to metadata
)

Basic API (No Password)

from interfaces.api import stc_api

# Initialize STC context
context = stc_api.initialize(seed="your-seed-phrase")

# Encrypt data (uses seed as password)
encrypted, metadata = context.encrypt("sensitive information")

# Decrypt data
decrypted = context.decrypt(encrypted, metadata)
print(decrypted)  # "sensitive information"

# Generate probabilistic hash
hash_result = context.hash("data to hash")

Quick API (One-liners)

from interfaces.api import stc_api

# Quick encrypt - returns encrypted data, metadata, and context
encrypted, metadata, context = stc_api.quick_encrypt(
    "sensitive data", 
    seed="your-seed"
)

# Quick decrypt - reconstructs context from metadata
decrypted = stc_api.quick_decrypt(
    encrypted, 
    metadata, 
    seed="your-seed"
)

Usage

Advanced: Custom Parameters

from interfaces.api.stc_api import STCContext

# Custom lattice parameters (smaller = faster, less security)
context = STCContext(
    seed="your-seed",
    lattice_size=128,  # Default: 128 (was 256 in v0.1.x)
    depth=6,           # Default: 6 (was 8 in v0.1.x)
    morph_interval=100 # Polymorphic flow morphing interval
)

# Encrypt with custom context
encrypted, metadata = context.encrypt(
    "data",
    password="password123"
)

# Derive keys
key = context.derive_key(length=32)

# Hash data
hash_value = context.hash("data")

State Management

# Save context state
state = context.save_state()

# Load state (for resuming)
context.load_state(state)

# Get context status
status = context.get_status()
print(status)

Features

v0.2.0 Enhancements

• ✅ Password-based encryption with MAC verification
• ✅ Metadata encryption using ephemeral keys
• ✅ Binary TLV format for compact metadata storage
• ✅ CEL entropy amplification with timing chains and multi-tier feedback
• ✅ PHE multi-path hashing (3-5 parallel paths, CEL-driven)
• ✅ Performance optimizations (76x speedup from v0.2.0-alpha)
• ✅ Entropy quality auditing and collision monitoring
• ✅ Backward compatibility with v0.1.x JSON format

Known Limitations

• Metadata size: ~786 KB constant overhead (reduced from 4 MB in alpha)
• Decoy vectors: Not yet supported (TLV serialization pending)
• Performance: 2.3s for small messages (acceptable for security-critical use)

See CHANGELOG.md for detailed version history and PERFORMANCE_OPTIMIZATIONS.md for optimization details.

Principles

1. No legacy cryptography - No XOR, no substitution-permutation networks, no block ciphers
2. No external randomness - All entropy from internal computation (timing deltas, state evolution)
3. Deterministic from seed - Same seed produces same initial state; state evolves with CEL dynamics
4. Context-sensitive polymorphism - Behavior adapts to operation chains
5. Ephemeral keys - Keys emerge and discard, never persist
6. Self-sovereign security - No cloud dependencies, no external services, full user control

Examples

See examples/ directory for practical demonstrations:

• password_manager/ - Secure credential storage with password-based encryption (v0.2.0)
• config_encryption/ - Configuration file encryption with metadata persistence
• validation/ - Example validation scripts

Run examples:

cd examples/password_manager
python password_manager.py

cd examples/config_encryption
python config_example.py

Testing

Run the full test suite:

# Run all tests
python -m unittest discover tests/

# Run specific test modules
python -m unittest tests.test_cel
python -m unittest tests.test_phe
python -m unittest tests.test_integration

All 37 tests pass in v0.2.0.

Development Status

v0.2.0 - Production-ready with known limitations (see above)

Roadmap

• v0.2.1: Variable-length integer encoding (metadata → ~100-200 KB)
• v0.2.2: Decoy vector TLV serialization
• v0.3.0: Streaming support for large files, migration utilities

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Add tests for new features
4. Submit a pull request

See docs/ for architecture and API documentation.

License

ANTI-CAPITALIST SOFTWARE LICENSE (v 1.4) - See LICENSE file for details

---

Citation

If you use STC in research, please cite:

@software{seigr_toolset_crypto,
  title = {Seigr Toolset Crypto: Post-Classical Cryptographic Engine},
  author = {Seigr-lab},
  year = {2025},
  version = {0.2.0},
  url = {https://github.com/Seigr-lab/SeigrToolsetCrypto}
}