> ## Documentation Index
> Fetch the complete documentation index at: https://hayate.shiina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.
# Hayate Security Model: Encryption, Key Exchange, and Trust
> Hayate uses ephemeral X25519 key exchange, HKDF-SHA256 derivation, and AES-256-GCM or ChaCha20-Poly1305 AEAD to secure every transfer end-to-end.
Hayate builds its trust model at the application layer, on top of the transport-level encryption QUIC already provides. Every transfer generates a fresh ephemeral keypair, performs an X25519 Diffie-Hellman exchange, and derives a session-specific 32-byte AEAD key using HKDF-SHA256. The actual file data — along with the filename, size, and integrity algorithm — is encrypted before any byte leaves your machine. An eavesdropper on the same LAN segment sees only opaque encrypted frames. Past sessions stay private even if your network is later compromised, because ephemeral keys are discarded the moment the transfer ends.
## Cryptographic Primitives
| Layer | Primitive |
| ---------------- | ------------------------------------------------------- |
| Key agreement | X25519 ECDH (ephemeral, forward-secret) |
| Key derivation | HKDF-SHA256 with optional passphrase mixed into IKM |
| Frame encryption | AES-256-GCM (hardware-accelerated) or ChaCha20-Poly1305 |
| Integrity | Blake3 / SHA-256 stream hash |
| Directory safety | Path-traversal rejection |
| Metadata | Filename and size encrypted before transmission |
## Key Exchange
At the start of every transfer, both the sender and receiver independently generate a fresh, one-time X25519 keypair. They exchange public keys over the QUIC connection, compute a shared secret via Diffie-Hellman, and feed that shared secret into HKDF-SHA256 to produce the final 32-byte AEAD key.
The HKDF derivation is bound to a *transcript* that includes the protocol version, cipher capability bytes, both public keys, and a random per-session salt sent in the clear. This means two transfers with the same passphrase but different ephemeral keys produce completely different session keys.
**Passphrase binding in Pairing Mode:** When you use `--code`, the phrase bytes are mixed directly into the HKDF input keying material (IKM) — not used as the salt. The effect is that two peers must have independently computed the same IKM (i.e., know the exact phrase) to arrive at the same session key. A third party who observes the handshake cannot derive the key without the phrase.
**Direct Mode:** When no passphrase is used, HKDF is still performed with the same transcript binding, but the IKM contains only the X25519 shared secret and a no-passphrase marker byte. Authentication relies on network locality instead of a shared secret.
## Forward Secrecy
Hayate's use of ephemeral X25519 keypairs guarantees forward secrecy. The private key material used to establish a session exists only in memory for the duration of that session. Once the transfer is complete, those keys are dropped and cannot be recovered. Recording encrypted traffic today will not enable decryption in the future, even if your passphrase is later compromised.
## Frame Encryption
The payload stream is split into 4 MiB chunks. Each chunk is encrypted as an independent AEAD frame before being written to the QUIC stream:
```text theme={null}
[ 12-byte Nonce ] [ Encrypted Payload ] [ 16-byte Authentication Tag ]
```
* A fresh, cryptographically random **12-byte nonce** is generated for every frame using the OS CSPRNG.
* The frame payload (raw data or Zstd-compressed data) is encrypted in-place with the negotiated AEAD cipher.
* A **16-byte authentication tag** is appended. The receiver verifies this tag before accepting any data.
Because each frame is independently authenticated, a single tampered byte anywhere in the stream causes that frame's AEAD check to fail, and Hayate closes the connection immediately. This prevents both replay attacks (a replayed frame with a mismatched nonce and context will fail authentication) and silent data corruption.
## Metadata Confidentiality
Before sending a single payload byte, Hayate encrypts the transfer metadata — filename, total size, transfer type (file or directory), and hash algorithm — using the negotiated session key and AEAD cipher. The receiver decrypts and validates this metadata block first, then prompts you for acceptance.
An eavesdropper on the local network cannot learn the name of the file you are sending, how large it is, or which hash algorithm you chose. All they observe is the handshake public keys, the random salt, and a stream of opaque ciphertext frames.
## Directory Safety
When you send a folder, Hayate packages it as a streaming tar archive. Receiving and extracting tar archives from an untrusted peer carries risk if the archive is maliciously crafted. Hayate applies strict extraction rules before writing any file to disk:
* **Path traversal (`..`)** — any entry whose resolved path escapes the output directory is rejected outright.
* **Absolute paths** — entries with absolute paths (e.g. `/etc/passwd`, `C:\Windows\system32\…`) are rejected.
* **Symbolic links** — symlink entries are ignored during extraction to prevent redirection attacks.
* **Hard links** — hard link entries are also rejected to prevent unexpected filesystem aliasing.
The Pairing Mode code phrase is **not a PAKE (Password-Authenticated Key Exchange)**. Hayate mixes the phrase into HKDF IKM, which provides phrase-binding but does not include the computational hardening that a dedicated PAKE protocol would add. A very short or guessable phrase (e.g. a single common word) offers less protection against an offline brute-force attack on a recorded handshake. Choose unpredictable phrases — Hayate's auto-generated 4-word phrases are drawn from a large word list for exactly this reason.
**Hardware AES acceleration:** Hayate automatically detects AES-NI (on x86/x86-64) and ARMv8 AES extensions (on aarch64) at runtime. When hardware acceleration is available, AES-256-GCM is selected automatically and delivers near-wire-speed encryption with minimal CPU overhead. On platforms without hardware AES, Hayate falls back to ChaCha20-Poly1305, which is a constant-time, software-optimised cipher that performs comparably on those architectures. You can force ChaCha20-Poly1305 on any platform by setting `HAYATE_FORCE_CHACHA20=1`.