README

Epicrypt is a capability-first PHP security toolkit.

It provides focused security building blocks for:

• Certificate / PKI / key exchange
• Crypto primitives
• Token security (JWT, payload, opaque)
• Password and secret protection
• Integrity verification
• Secure generation
• Data protection workflows
• Security utilities (signed URL, CSRF, reset/action tokens)

Installation

composer require infocyph/epicrypt

Requirements

• PHP >=8.4
• ext-sodium, ext-openssl, ext-json, ext-mbstring, ext-hash

Documentation

Primary documentation:

• https://docs.infocyph.com/projects/Epicrypt

Security

Please review SECURITY.md for vulnerability reporting guidelines.

Code of Conduct

Please review CODE_OF_CONDUCT.md before contributing.

Usage Examples

Encrypt and decrypt a string

<?php

use Infocyph\Epicrypt\DataProtection\StringProtector;
use Infocyph\Epicrypt\Generate\KeyMaterial\KeyMaterialGenerator;

$key = (new KeyMaterialGenerator())->forSecretBox();
$protector = new StringProtector();

$ciphertext = $protector->encrypt('secret-value', $key);
$plaintext = $protector->decrypt($ciphertext, $key);

Encrypt and decrypt a file

<?php

use Infocyph\Epicrypt\DataProtection\FileProtector;
use Infocyph\Epicrypt\Generate\KeyMaterial\KeyMaterialGenerator;

$key = (new KeyMaterialGenerator())->forSecretStream();
$files = new FileProtector();

$files->encrypt('/data/plain.txt', '/data/plain.txt.epc', $key);
$files->decrypt('/data/plain.txt.epc', '/data/plain.out.txt', $key);

Rotate keys with a key ring

<?php

use Infocyph\Epicrypt\DataProtection\StringProtector;
use Infocyph\Epicrypt\Security\KeyRing;

$ring = new KeyRing([
    '2026-01' => $oldKey,
    '2026-05' => $newKey,
], '2026-05');

$protector = new StringProtector();
$ciphertext = $protector->encryptWithKeyRing('rotating-data', $ring);
$result = $protector->decryptWithKeyRingResult($ciphertext, $ring);

Hash, verify, and rehash password

<?php

use Infocyph\Epicrypt\Password\PasswordHasher;

$hasher = new PasswordHasher();
$hash = $hasher->hashPassword('MyStrongPassword!2026');

$isValid = $hasher->verifyPassword('MyStrongPassword!2026', $hash);
$rehash = $hasher->verifyAndRehash('MyStrongPassword!2026', $hash);

Issue and verify CSRF token

<?php

use Infocyph\Epicrypt\Security\CsrfTokenManager;

$csrf = new CsrfTokenManager('csrf-secret');
$token = $csrf->issueToken('session-1');

$ok = $csrf->verifyToken('session-1', $token);

Generate and verify signed URL

<?php

use Infocyph\Epicrypt\Security\SignedUrl;

$signed = new SignedUrl('url-secret');
$url = $signed->generate('https://example.com/download', ['file' => 'report.pdf'], time() + 300);

$ok = $signed->verify($url);

Issue and verify JWT (HS512)

<?php

use Infocyph\Epicrypt\Token\Jwt\Enum\SymmetricJwtAlgorithm;
use Infocyph\Epicrypt\Token\Jwt\SymmetricJwt;
use Infocyph\Epicrypt\Token\Jwt\Validation\RegisteredClaims;

$issuer = new SymmetricJwt(SymmetricJwtAlgorithm::HS512);
$token = $issuer->encode([
    'iss' => 'issuer-service',
    'aud' => 'api',
    'sub' => 'user-1',
    'jti' => 'jwt-1',
    'nbf' => time(),
    'exp' => time() + 600,
], 'signing-secret');

$verifier = new SymmetricJwt(
    SymmetricJwtAlgorithm::HS512,
    new RegisteredClaims('issuer-service', 'api', 'user-1', 'jwt-1'),
);

$ok = $verifier->verify($token, 'signing-secret');

Generate certificate with SAN

<?php

use Infocyph\Epicrypt\Certificate\CertificateBuilder;
use Infocyph\Epicrypt\Certificate\CertificateOptions;
use Infocyph\Epicrypt\Certificate\Enum\OpenSslRsaBits;
use Infocyph\Epicrypt\Certificate\KeyPairGenerator;

$pair = KeyPairGenerator::openSsl(bits: OpenSslRsaBits::BITS_3072)->generate();
$dn = ['commonName' => 'service.example.test'];

$options = new CertificateOptions(
    sanDns: ['service.example.test', 'api.example.test'],
);

$certPem = CertificateBuilder::openSsl()->selfSign($dn, $pair['private'], options: $options);