Requirements
- PHP 8.1 or newer
- Extensions/support for
hash(PBKDF2/HMAC/SHA-256) andrandom_bytes
Package contents
src/HotkeyEncryption.php— core HKEY v1 implementation (HKey\HotkeyEncryption)composer.json— package metadata and PSR-4 autoload (HKey\)example.php— runnable encrypt/decrypt demo
Quick start
require 'src/HotkeyEncryption.php';
use HKey\HotkeyEncryption;
$hkey = new HotkeyEncryption(
'lab.freezer.alpha', // context (gesture salt)
['Ctrl+Alt+H', 'Shift+K', 'Meta+E', 'Y'] // ordered chord sequence
);
$packetJson = $hkey->encryptText('sensitive payload');
$plain = $hkey->decryptText($packetJson);
echo $hkey->getDigest(); // sequence digest (commitment)
echo $plain; // "sensitive payload"
Run the example
php sdk/php/example.php
API overview
new HotkeyEncryption(string $gestureSalt, array $chords, int $iterations = 210000)— normalizes chords and derives keys.encrypt(string $plaintext, ?string $nonce = null): array— returns an HKEY v1 packet array (random 12-byte nonce by default).decrypt(array $packet): string— verifies tag (constant-time) then returns plaintext; throws on failure.encryptText(string $text): string/decryptText(string $packetJson): string— JSON helpers.getDigest(): string— SHA-256 hex digest of the normalized sequence encoding (useful for labels/audit, not secret).sequenceEncoding(): string— canonicalSEQv1:<salt>\n...input.
HKEY v1 behavior
- Normalization: canonical modifier order (
Ctrl, Alt, Shift, Meta) and key names; case/spacing variants normalize to the same chord. - KDF: PBKDF2-HMAC-SHA256, 210,000 iterations, 32-byte master key, with HMAC-derived
enc/macsubkeys. - Encryption: HKEY-CTR-HMAC (HMAC-SHA256 keystream + Encrypt-then-MAC tag over nonce, ciphertext, and length).
- Packet: JSON with
version,alg,kdf,nonce,ciphertext,tag,digest(base64 for binary fields).
Good practices
- Use 4+ chords with mixed modifiers/keys and a unique salt per purpose, tenant, or environment.
- Never log raw chord sequences or derived keys.
- Handle decryption failures as authentication failures (do not trust partial output).
This is a reference/educational implementation. For regulated or high-risk production use, seek independent review and pair with audited, standardized AEAD primitives and secure operational controls.