ESPHome Encryption

ESPHome Encryption

Ava Pro 0.7.3 adds support for encrypted voice-satellite connections using the Noise NNpsk0 protocol. This encrypts the ESPHome API connection between Ava and Home Assistant, protecting voice audio and control commands on the local network.

---

Protocol

Ava implements Noise_NNpsk0_25519_ChaChaPoly_SHA256 — the same Noise protocol used by ESPHome's native encryption.

Component	Algorithm
Handshake pattern	NNpsk0 (pre-shared key, no static keys)
Key exchange	X25519 (Curve25519 ECDH)
Cipher	ChaCha20-Poly1305 (AEAD)
Hash	SHA-256
PSK size	32 bytes

Ava is the responder; Home Assistant (ESPHome) is the initiator. The PSK is mixed into the handshake first, then both sides exchange ephemeral keys and perform Diffie-Hellman.

---

Implementation

Ava's Noise implementation is pure Kotlin — no native library dependency, no external crypto framework. The entire handshake, key derivation, and transport encryption run inside the app. This keeps the encrypted path auditable and free of platform-specific crypto quirks.

---

PSK Format

The pre-shared key is a 32-byte value, encoded as Base64 in configuration.

# Example PSK (do not use in production)
Base64: dYXZqqvMbjnQyOoZmQq1cQzMSxqQmMSxqQmMSxqQmQ=

The PSK must match the one configured in your ESPHome device's configuration.

---

Setup

1. Generate a PSK

Generate a 32-byte random key and encode it as Base64:

openssl rand -base64 32

2. Configure ESPHome

In your ESPHome device configuration:

api:
  encryption:
    key: "your-base64-psk-here"

3. Configure Ava

1. Go to Settings → Voice Config → ESPHome
2. Find API Encryption Key
3. Tap Generate to create a new PSK, or enter the same Base64 PSK you used in ESPHome
4. Tap Copy to copy the key for pasting into your ESPHome config
5. Ava will encrypt the connection on next reconnect

The encryption toggle shows Unlock (plaintext) or Encrypt (key set). When set to Encrypt, the connection uses the Noise NNpsk0 handshake. Clear removes the key and returns to plaintext.

---

Verification

When encryption is active:

• The ESPHome API connection is encrypted end-to-end
• Voice audio, wake events, timer events, and announcements are all encrypted
• A wrong PSK causes the handshake to fail closed — no unencrypted fallback

---

Compatibility

• Requires ESPHome 2026.10.1+ (Ava's built-in ESPHome baseline, raised in 0.7.3)
• Works alongside existing unencrypted connections (encryption is per-device)
• AvaVoice (LAN intercom) uses its own separate encryption path

---

Back to Home