HKEY Docs
← Back to SDKs & downloads

Specification

HKEY v1 — Hotkey Encryption System

A clear, interoperable specification for gesture-derived key derivation and authenticated packet protection. HKEY turns ordered hotkey chord sequences plus a context salt into deterministic keys and portable, tamper-evident packets.

Status and scope

Status: Conceptual reference design implemented by the SDKs in this project. Scope: Educational and interoperable demo specification for human-memorized hotkey-chord secrets.

HKEY v1 is not presented as a drop-in replacement for audited, standardized cryptography in regulated environments. For high-risk deployments, pair HKEY concepts with standards-based primitives and independent review.

1. Goals

2. Terminology

3. Chord normalization

3.1 Modifier order

Ctrl, Alt, Shift, Meta (Win/Cmd/Super), then the primary key.

3.2 Key rules

3.3 Fingerprint and encoding

Fingerprint: <mods joined by '+'>+<KEY> (e.g. Ctrl+Alt+K, Shift+Space, Meta+Enter).

Sequence encoding (UTF-8):

SEQv1:<gesture_salt>
<fingerprint1>
<fingerprint2>
...

4. Key derivation

  1. Input: password = UTF8(sequence_encoding), salt = UTF8("HKEYv1|" + gesture_salt)
  2. Stretch: PBKDF2-HMAC-SHA256, iterations = 210000, dkLen = 32 → master key (MK)
  3. Subkeys: enc_key = HMAC-SHA256(MK, "hkey:enc:v1"), mac_key = HMAC-SHA256(MK, "hkey:mac:v1")
  4. Digest: SHA256(sequence_encoding) hex (public-safe commitment)

5. Encryption: HKEY-CTR-HMAC (Encrypt-then-MAC)

  1. Generate random nonce (12 bytes).
  2. Keystream blocks: KS_i = HMAC-SHA256(enc_key, nonce || counter_i_be32).
  3. ciphertext = plaintext XOR keystream.
  4. tag = HMAC-SHA256(mac_key, "HKEYv1" || nonce || ciphertext || uint64_be(len(plaintext))).
  5. Verify tag in constant-time comparison before releasing plaintext on decrypt.

6. Packet format (JSON, v1)

{
  "version": "HKEYv1",
  "alg": "HKEY-CTR-HMAC-SHA256",
  "kdf": "PBKDF2-HMAC-SHA256-210000",
  "nonce": "<base64>",
  "ciphertext": "<base64>",
  "tag": "<base64>",
  "digest": "<sha256 hex of sequence encoding>"
}

7. Security considerations

8. Interoperability test shape

Implementations must agree on normalization and verification for identical inputs (e.g. sequence ["Ctrl+Alt+H","Shift+K","Meta+E","Y"], salt demo.torus.field, plaintext hello hkey). Use fixed nonces only in test mode; production nonces must be random.

For implementation details and examples, download the SDKs or read the per-language SDK documentation on this site.