composer require maatify/cryptouse Maatify\Crypto\DX\CryptoProvider;
use Maatify\Crypto\Reversible\DTO\ReversibleCryptoMetadataDTO;
$crypto = $container->get(CryptoProvider::class);
$service = $crypto->context("user:email:v1");
$encrypted = $service->encrypt("hello world");
$metadata = new ReversibleCryptoMetadataDTO(
$encrypted['result']->iv,
$encrypted['result']->tag
);
$plain = $service->decrypt(
$encrypted['result']->cipher,
$encrypted['key_id'],
$encrypted['algorithm'],
$metadata
);For full documentation and detailed usage guides, see the official documentation book:
The documentation includes:
- Architecture overview
- Key rotation lifecycle
- Context-based encryption
- Password hashing pipeline
- Security design guarantees
- Integration examples
This library is a Security-First cryptographic system providing a set of strict, isolated, and frozen cryptographic primitives. It is designed to be extracted as a standalone library, independent of any specific application framework.
The system enforces a strict separation of concerns between key lifecycle management, key derivation, reversible encryption, and password hashing. It prioritizes safety, deterministic behavior, and fail-closed security over developer convenience.
All cryptographic primitives within this library are frozen, meaning their core logic, algorithms, and security boundaries are immutable. Any significant change to these primitives requires a formal architectural review.
The library follows modern cryptographic best practices:
- AES-256-GCM authenticated encryption
- HKDF domain separation (RFC 5869)
- Argon2id password hashing
- Secure randomness via
random_bytes() - Strict key rotation lifecycle (Active / Inactive / Retired)
- Fail-closed cryptographic operations
The cryptographic system is composed of five distinct, decoupled components:
Purpose: Secure, irreversible password hashing and verification.
What it DOES
Implements a strict pipeline of:
HMAC-SHA256 (Pepper) → Argon2id
Handles:
- hashing
- verification
- rehash checks
What it DOES NOT do
- manage storage of hashes
- retrieve pepper secrets
Security Boundary
Operates in total isolation from encryption keys and relies on:
PasswordPepperProviderInterface
Purpose: Management of cryptographic key lifecycles and rotation policies.
What it DOES
Enforces strict invariants:
exactly one ACTIVE key at any time
Manages key states:
- ACTIVE
- INACTIVE
- RETIRED
This allows seamless key rotation without downtime.
What it DOES NOT do
- perform encryption or decryption
- load keys from storage
Security Boundary
Acts as the sole authority on which key may encrypt new data.
Purpose: Key Derivation Function implementing RFC 5869.
What it DOES
Derives independent keys from a root key using explicit contexts.
Example contexts:
notification:email:v1
auth:session:v1
payment:token:v1
What it DOES NOT do
- generate root secrets
- perform encryption
Security Boundary
Ensures compromise of one domain cannot affect another.
Purpose: Symmetric encryption and decryption.
Algorithm:
AES-256-GCM
What it DOES
- encrypt data
- decrypt data
What it DOES NOT do
- manage keys
- derive keys
Security Boundary
Fail-closed behavior:
- invalid tag → exception
- corrupted ciphertext → exception
- unsupported algorithm → exception
Weak algorithms like ECB are explicitly forbidden.
Purpose: Developer Experience orchestration layer.
Provides the CryptoProvider facade.
Example:
$crypto->context("user:email:v1");What it DOES
Connects primitives into usable pipelines.
What it DOES NOT do
Contains no cryptographic logic.
All security guarantees exist in the lower layers.
The library supports three secure pipelines.
Used for authentication.
Input Password
↓
HMAC-SHA256 (Pepper)
↓
Argon2id (Salted)
↓
Password Hash
Used for sensitive application data.
Root Keys (KeyRotation)
↓
HKDF (Context)
↓
Derived Keys
↓
AES-256-GCM Encryption
Used only for internal system secrets.
Root Keys (KeyRotation)
↓
AES-256-GCM
Root Keys
Managed by KeyRotation.
Never used directly for domain data in the standard pipeline.
Derived Keys
Generated via HKDF.
Used for actual encryption.
Password Secrets
Pepper is fully isolated from encryption keys.
Fail-Closed Behavior
All modules throw exceptions on failure.
No silent failures. No fallback algorithms.
Explicit Versioning
Contexts must be versioned.
Example:
auth:token:v1
Domain Separation
Different data domains must use different contexts.
Key Rotation Safety
Old keys remain valid for decryption while new data always uses the active key.
No Implicit Defaults
Algorithms, keys, and contexts must always be explicit.
No Hidden State
Modules are stateless.
They do not cache secrets or persist runtime state.
Not a Framework
No dependency on Laravel, Symfony, etc.
Not a Key Management System
Does not store keys.
Keys must be injected by the host application.
Not a Secrets Loader
Does not read .env.
Secret management belongs to the host application.
Not a Generic Crypto DSL
The library intentionally exposes specific approved primitives only:
- AES-256-GCM
- Argon2id
- HKDF
No driver abstraction.
This library is production-ready.
It was designed from the start to be extractable as a standalone package.
Frozen Components
- Password
- KeyRotation
- HKDF
- Reversible
Their security contracts are locked.
Optional Components
DX layer is optional.
Consumers may wire primitives manually.
This library is production-ready and follows Semantic Versioning.