Skip to main content

Gateway Security and AES

Security principal​

The Physical Gateway is the only permanent MQTT/AES principal. A Gateway-mediated Child does not receive an independent MQTT credential or encryptionKey.

AES v1​

Gateway-cloud traffic reuses the canonical AirNgin AES v1 contract:

  • AES-256-GCM
  • Base64 key decoding to 32 bytes
  • fresh random 12-byte nonce, never reused with the same key
  • version = "1.0"
  • timestamp in Unix UTC seconds
  • accepted timestamp window: ±60 seconds
  • replay nonce cache covering at least the acceptance window

Envelope:

{
  "nonce": "<base64>",
  "ciphertext": "<base64>",
  "tag": "<base64>",
  "version": "1.0",
  "timestamp": 1813000001,
  "deviceSerial": "AIRN1234567890",
  "more": null
}

For Gateway traffic, envelope deviceSerial always identifies the Physical Gateway, even when the business payload concerns a Child.

Receive validation order​

parse envelope
→ required fields/version
→ timestamp window
→ replay nonce check
→ Base64 decode
→ AES-GCM authenticate/decrypt
→ record nonce
→ parse plaintext JSON
→ validate business/topic contract
→ dispatch

Invalid input is dropped and must not reboot the Gateway, mutate state, or erase credentials.

Credential isolation​

Never expose in HTML or logs:

  • Gateway encryptionKey
  • MQTT password
  • API access token
  • HTML temporary password
  • Local API raw token

HTML exception​

HTML Live topics do not use the Gateway encryptionKey. Their security is:

WSS/TLS + temporary MQTT credential + session-scoped broker ACL

See HTML Live MQTT.