Requirements
- Python 3.10+
- Standard library only (
hashlib,hmac,secrets,base64,json)
Package contents
hkey/core.py— normalization, PBKDF2 derivation, HKEY-CTR-HMAC encrypt/decrypthkey/__init__.py— public exports (HotkeyEncryption,HKeyError)example.py— runnable demopyproject.toml— local install metadata
Install (local)
pip install -e ./sdk/python
# or run directly with PYTHONPATH pointing to sdk/python
Quick start
from hkey import HotkeyEncryption
hkey = HotkeyEncryption(
gesture_salt="lab.freezer.alpha",
chords=["Ctrl+Alt+H", "Shift+K", "Meta+E", "Y"],
)
packet_json = hkey.encrypt_text("sensitive payload")
plain = hkey.decrypt_text(packet_json)
print(hkey.digest) # sequence digest
print(plain) # "sensitive payload"
Run the example
PYTHONPATH=sdk/python python3 sdk/python/example.py
API overview
HotkeyEncryption(gesture_salt: str, chords: Sequence[str], iterations: int = 210000)encrypt(plaintext: bytes | str, nonce: bytes | None = None) -> dictdecrypt(packet: dict) -> bytes— authenticates withhmac.compare_digestbefore releaseencrypt_text(text: str) -> str/decrypt_text(packet_json: str) -> strdigestproperty,sequence_encoding(),normalize_chord()
HKEY v1 behavior
- Normalization: canonical modifier order and key names for cross-platform consistency.
- Derivation: PBKDF2-HMAC-SHA256 (210k, 32 bytes) over
SEQv1:<salt>\n..., split into enc/mac subkeys via HMAC labels. - Packet: HKEY-CTR-HMAC with 12-byte random nonce and Encrypt-then-MAC tag; JSON-encoded for portability.
Good practices
- Prefer long, unpredictable chord sequences and unique context salts.
- Add fixed-nonce test vectors when validating interop with PHP/TS/Mojo.
- Keep raw sequences out of logs and error messages.
Educational reference design. For sensitive or regulated production data, obtain security review and consider audited standard AEAD deployments.