Skip to main content

Direct Device application-layer security

AirNgin can add AES-256-GCM protection to eligible Direct Device MQTT messages in addition to transport-layer TLS.

This layer protects payload confidentiality and integrity at the application level. It is optional for Direct Device integrations unless the product/project policy enables it.

Device-specific key​

Provisioning provides a Base64-encoded encryptionKey that decodes to 32 bytes. That key is used for the current Direct Device encrypted topics. encryptionKeyProject is reserved and is not used by the current device-context AES topics.

AES-256-GCM envelope​

Canonical logical envelope:

{
  "ciphertext": "base64",
  "tag": "base64",
  "nonce": "base64",
  "version": "1.0",
  "timestamp": 0,
  "deviceSerial": "AIRN1234567890",
  "more": ""
}

ciphertext​

AES-GCM encrypted payload, Base64 encoded.

tag​

Authentication tag produced by AES-GCM. A message with an invalid tag must be dropped without changing Device state.

nonce​

Exactly 12 random bytes before Base64 encoding. Never reuse a nonce with the same key.

version​

Current AES envelope version: 1.0.

timestamp​

UTC Unix time in seconds. Receivers validate freshness using the current platform acceptance window and reject stale/future messages.

deviceSerial​

The canonical AirNgin DeviceSerial for the cryptographic principal represented by the envelope.

Replay protection​

After successful authentication, accepted nonces must be cached for at least the replay-acceptance window so the same message cannot be replayed.

Encrypted topic naming​

For Direct Device topics that support this layer, append:

/AES

Examples:

projectCode/DeviceToServer/AES
projectCode/ServerToDevice/{deviceSerial}/AES

Direct Device topics that remain non-AES​

The current canonical contract keeps these public/project-level topics unencrypted at this layer:

projectCode/SendScenarioSetting
projectCode/ReceiveRunScenario
projectCode/Time
projectCode/Time/Tehran

TLS and AES are complementary security layers, not replacements for one another.