azaharizaman/nexus-crypto

The Nexus\Crypto package provides a complete cryptographic primitive library designed for long-term security and future-proofing against quantum computing threats. By abstracting all cryptographic operations behind interfaces, the package enables seamless migration from classical algorithms (RSA, ECDSA, AES) to post-quantum alternatives (Dilithium, Kyber) simply by changing bindings in the application layer.

Core Principles

Algorithm Agility: All crypto operations via interfaces, enabling algorithm swapping without code changes
Post-Quantum Readiness: Hybrid mode support planned for dual classical + PQC signing/encryption
Stateless Design: All persistence via KeyStorageInterface - no framework dependencies
Immutable Value Objects: All cryptographic results as readonly data structures
Audit Trail: All operations compatible with Nexus\AuditLogger for compliance

Features

Phase 1 (Current - Classical Algorithms)

Hashing: SHA-256/384/512, BLAKE2b via Sodium
Symmetric Encryption: AES-256-GCM (authenticated), ChaCha20-Poly1305
Asymmetric Signing: Ed25519, RSA-2048/4096, ECDSA P-256, HMAC-SHA256
Key Management: Envelope encryption, automated rotation via Scheduler
Feature Flags: Gradual rollout support with CRYPTO_LEGACY_MODE

Phase 2 (Planned - Hybrid PQC)

Hybrid Signing: Dual ECDSA + Dilithium signatures
Hybrid KEM: Dual X25519 + Kyber key encapsulation
Transparent Migration: Existing code works unchanged

Phase 3 (Future - Pure PQC)

Pure PQC Algorithms: ML-DSA, ML-KEM (NIST standards)
Classical Deprecation: Full quantum-resistant operation

Installation

composer require azaharizaman/nexus-crypto

Required PHP Extensions

php -m | grep -E "(sodium|openssl)"

ext-sodium: Required for modern algorithms (ChaCha20, Ed25519, BLAKE2b)
ext-openssl: Required for legacy algorithms (RSA, AES-CBC)

Integration Requirements

Consuming applications must implement:

KeyStorageInterface - For persistent key storage
Service Container Bindings - Bind all crypto interfaces
Master Key Management - Secure master key for envelope encryption
(Optional) Scheduler Integration - For automated key rotation

Architecture

┌─────────────────────────────────────────────────────────────────┐
│ CONSUMING PACKAGE │
│ (e.g., Nexus\Export, Nexus\Connector, Nexus\Finance) │
│ │
│ Calls: $crypto->encrypt(data) │
│ Calls: $crypto->sign(data) │
│ Consumes: HashResult, EncryptedData, SignedData │
└─────────────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ NEXUS\CRYPTO (THIS PACKAGE) │
│ │
│ CryptoManager ──► HasherInterface │
│ │ SymmetricEncryptorInterface │
│ │ AsymmetricSignerInterface │
│ │ KeyGeneratorInterface │
│ └──► KeyStorageInterface │
│ │
│ Enums: HashAlgorithm, SymmetricAlgorithm, AsymmetricAlgorithm │
│ Value Objects: HashResult, EncryptedData, SignedData, KeyPair │
└─────────────────────────────────────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────────┐
│ APPLICATION LAYER (Consuming App) │
│ │
│ KeyStorage Implementation ─► Database/Redis/Filesystem │
│ Service Bindings ─► IoC Container (Laravel/Symfony) │
│ Master Key Management ─► Secure configuration │
│ KeyRotationHandler ─► Scheduler integration (optional) │
└─────────────────────────────────────────────────────────────────┘

Usage

1. Hash Data (Integrity Checking)

use Nexus\Crypto\Services\CryptoManager;
use Nexus\Crypto\Enums\HashAlgorithm;

$crypto = app(CryptoManager::class);

// Hash with default SHA-256
$result = $crypto->hash('sensitive data');
// HashResult(hash: '5d41...', algorithm: SHA256, salt: null)

// Hash with specific algorithm
$result = $crypto->hash('sensitive data', HashAlgorithm::BLAKE2B);

// Verify hash
if ($crypto->verifyHash('sensitive data', $result)) {
 // Data integrity confirmed
}

2. Encrypt Data (Symmetric Encryption)

use Nexus\Crypto\Enums\SymmetricAlgorithm;

// Encrypt with default AES-256-GCM
$encrypted = $crypto->encrypt('confidential information');
// EncryptedData(
// ciphertext: '8f3a...',
// iv: '4b2c...',
// tag: '9d1e...',
// algorithm: AES256GCM,
// metadata: []
// )

// Decrypt
$plaintext = $crypto->decrypt($encrypted);

// Encrypt with specific key
$keyId = 'tenant-123-finance';
$encrypted = $crypto->encryptWithKey('payroll data', $keyId);
$plaintext = $crypto->decryptWithKey($encrypted, $keyId);

3. Sign Data (Digital Signatures)

use Nexus\Crypto\Enums\AsymmetricAlgorithm;

// Generate key pair
$keyPair = $crypto->generateKeyPair(AsymmetricAlgorithm::ED25519);

// Sign data
$signed = $crypto->sign('financial report', $keyPair->privateKey);
// SignedData(
// data: 'financial report',
// signature: 'a8f3...',
// algorithm: ED25519,
// publicKey: '7b2c...'
// )

// Verify signature
if ($crypto->verifySignature($signed)) {
 // Signature valid - data authentic and unmodified
}

4. HMAC Signing (Webhook Verification)

// Generate HMAC signature
$signature = $crypto->hmac($payload, $secret);

// Verify HMAC
if ($crypto->verifyHmac($payload, $signature, $secret)) {
 // Webhook authentic
}

5. Key Rotation (Automated via Scheduler)

// Manual rotation
$newKey = $crypto->rotateKey('tenant-123-finance');

// Automated rotation (configured in CryptoServiceProvider)
// KeyRotationHandler checks all keys daily and rotates expired ones
// Based on expiresAt field in EncryptionKey value object

Value Objects

HashResult

final readonly class HashResult
{
 public function __construct(
 public string $hash, // Hex-encoded hash
 public HashAlgorithm $algorithm, // Algorithm used
 public ?string $salt = null // Optional salt (for KDF)
 ) {}
 
 public function toArray(): array;
 public static function fromArray(array $data): self;
}

EncryptedData

final readonly class EncryptedData
{
 public function __construct(
 public string $ciphertext, // Base64-encoded encrypted data
 public string $iv, // Initialization vector
 public string $tag, // Authentication tag (GCM/Poly1305)
 public SymmetricAlgorithm $algorithm, // Algorithm used
 public array $metadata = [] // Additional context
 ) {}
 
 public function toArray(): array;
 public static function fromArray(array $data): self;
}

SignedData

final readonly class SignedData
{
 public function __construct(
 public string $data, // Original data
 public string $signature, // Signature bytes
 public AsymmetricAlgorithm $algorithm, // Algorithm used
 public ?string $publicKey = null // Public key (optional)
 ) {}
 
 public function isQuantumResistant(): bool; // Check if PQC algorithm
 public function toArray(): array;
 public static function fromArray(array $data): self;
}

KeyPair

final readonly class KeyPair
{
 public function __construct(
 public string $publicKey, // Base64-encoded public key
 public string $privateKey, // Base64-encoded private key
 public AsymmetricAlgorithm $algorithm // Algorithm used
 ) {}
}

EncryptionKey

final readonly class EncryptionKey
{
 public function __construct(
 public string $key, // Base64-encoded key material
 public SymmetricAlgorithm $algorithm, // Algorithm
 public DateTimeImmutable $createdAt,
 public ?DateTimeImmutable $expiresAt = null
 ) {}
 
 public function isExpired(ClockInterface $clock): bool;
}

Enums

HashAlgorithm

enum HashAlgorithm: string
{
 case SHA256 = 'sha256';
 case SHA384 = 'sha384';
 case SHA512 = 'sha512';
 case BLAKE2B = 'blake2b';
 
 public function isQuantumResistant(): bool;
 public function getSecurityLevel(): int; // Bits (e.g., 256)
}

SymmetricAlgorithm

enum SymmetricAlgorithm: string
{
 case AES256GCM = 'aes-256-gcm';
 case AES256CBC = 'aes-256-cbc';
 case CHACHA20POLY1305 = 'chacha20-poly1305';
 
 public function isAuthenticated(): bool; // GCM/Poly1305 = true
 public function requiresIV(): bool;
 public function getKeyLength(): int; // Bytes
}

AsymmetricAlgorithm

enum AsymmetricAlgorithm: string
{
 case HMACSHA256 = 'hmac-sha256';
 case ED25519 = 'ed25519';
 case RSA2048 = 'rsa-2048';
 case RSA4096 = 'rsa-4096';
 case ECDSAP256 = 'ecdsa-p256';
 
 // Phase 2 (stubs for now)
 case DILITHIUM3 = 'dilithium3';
 case KYBER768 = 'kyber768';
 
 public function isQuantumResistant(): bool;
 public function getSecurityLevel(): int;
}

Security Considerations

Envelope Encryption

All data encryption keys (DEKs) are encrypted with the master key (APP_KEY) before storage:

Plaintext → Encrypt with DEK → Ciphertext
DEK → Encrypt with Master Key → Encrypted DEK (stored in database)

Key Rotation

Automated: KeyRotationHandler runs daily via Nexus\Scheduler
Frequency: 90-day default (configurable)
Audit Trail: All rotations logged to key_rotation_history
Zero Downtime: Old keys retained for decryption of existing data

Algorithm Selection

// Recommended defaults (Phase 1)
HashAlgorithm::SHA256 // General hashing
SymmetricAlgorithm::AES256GCM // Data encryption (authenticated)
AsymmetricAlgorithm::ED25519 // Digital signatures (fast)

// Legacy support
SymmetricAlgorithm::AES256CBC // Backward compatibility
AsymmetricAlgorithm::RSA2048 // Standards compliance

Error Handling

use Nexus\Crypto\Exceptions\{
 EncryptionException,
 DecryptionException,
 SignatureException,
 InvalidKeyException,
 UnsupportedAlgorithmException,
 FeatureNotImplementedException
};

try {
 $encrypted = $crypto->encrypt($data);
} catch (EncryptionException $e) {
 // Handle encryption failure
 $logger->error('Encryption failed', ['error' => $e->getMessage()]);
}

try {
 $signed = $hybridSigner->sign($data); // Phase 2 feature
} catch (FeatureNotImplementedException $e) {
 // Fall back to classical signing
 $signed = $crypto->sign($data);
}

Performance

Benchmarks (Phase 1 - Classical Algorithms)

Operation	Algorithm	Input Size	Target	Actual
Hash	SHA-256	1 KB	< 1ms	~0.3ms
Hash	BLAKE2b	1 KB	< 1ms	~0.2ms
Encrypt	AES-256-GCM	1 KB	< 2ms	~0.8ms
Decrypt	AES-256-GCM	1 KB	< 2ms	~0.9ms
Sign	Ed25519	1 KB	< 5ms	~1.2ms
Verify	Ed25519	1 KB	< 5ms	~1.5ms

Benchmarks on PHP 8.3, ext-sodium 2.0.23

Roadmap

✅ Phase 1: Classical Algorithms (Q4 2025)

Core interfaces and value objects
Sodium-based implementations
Key rotation handler
Feature flag support
Legacy code refactoring

🔄 Phase 2: Hybrid PQC Mode (Q3 2026)

Monitor liboqs-php maturity
Implement HybridSignerInterface
Implement HybridKEMInterface
Dual signature verification
Migration tooling

🔮 Phase 3: Pure PQC (Post-2027)

NIST ML-DSA/ML-KEM standards finalized
Pure PQC implementations
Classical algorithm deprecation
Performance optimization

Contributing

This package follows the Nexus architecture principles:

Framework-agnostic: No Laravel dependencies in src/
Contract-driven: All persistence via interfaces
Immutable: Readonly value objects only
Testable: All dependencies injected

Documentation

User Documentation

Getting Started - Quick start guide with prerequisites, core concepts, and first integration
API Reference - Complete documentation of all interfaces, services, value objects, enums, and exceptions
Integration Guide - Laravel and Symfony integration with complete examples
Basic Usage Examples - Common cryptographic operations
Advanced Usage Examples - Key rotation, envelope encryption, multi-tenant patterns

Project Documentation

IMPLEMENTATION_SUMMARY.md - Development progress, metrics, and design decisions
REQUIREMENTS.md - Complete requirements tracking (42 requirements, 88.1% complete)
TEST_SUITE_SUMMARY.md - Testing strategy and recommendations (85 tests at application layer)
VALUATION_MATRIX.md - Package valuation metrics ($225K estimated value, 1,719% ROI)

License

MIT License - see LICENSE file for details.

Security Disclosure

For security vulnerabilities, please email: azahari@nexusnv.net (DO NOT file public issues)

URL: https://packagist.org/packages/azaharizaman/nexus-crypto

⇱ azaharizaman/nexus-crypto - Packagist.org