README

Framework-agnostic cryptographic abstraction layer providing algorithm agility and post-quantum readiness for the Nexus ERP ecosystem.

Overview

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)

azaharizaman / nexus-crypto

Maintainers

Package info

Statistics

Security