HMAC Authentication

To ensure the integrity and authenticity of your telemetry data, AdaTrack uses HMAC-SHA256 (Hash-Based Message Authentication Code) for all UDP packets. This cryptographic method ensures that only your authorized devices can send data to your account and that the data has not been tampered with in transit.

Why HMAC?

In a connectionless UDP environment, traditional session-based security (like TLS/TCP) is too heavy for constrained IoT devices. HMAC provides a stateless, low-overhead alternative that:

• Verifies Identity: Confirms the sender possesses the unique shared secret.

• Ensures Integrity: Detects if any part of the packet was modified.

• Prevents Replays: Using a timestamp prevents attackers from recording and re-sending old packets.

The Authentication Flow

1. Shared Secret: Every device is assigned a unique 32-byte secret key (stored securely on the device and in the AdaTrack database).

2. Signing (Device): The device constructs the telemetry packet (DeviceID + Timestamp + Payload) and calculates the signature using HMAC-SHA256 and its secret key.

3. Transmission: The device sends the full packet, including the signature, via UDP.

4. Verification (Backend):

   • AdaTrack receives the packet and extracts the Device ID.

   • It fetches the shared secret for that device (from a high-speed cache).

   • It re-calculates the HMAC signature using the received data.

   • It performs a constant-time comparison between the calculated signature and the received signature.

   • If they match, the packet is accepted; otherwise, it is immediately discarded.

Packet Format with HMAC

Your device must send its data in the following binary order:

Section	Size	Description
Header	24 Bytes	Consists of DeviceID (16B) and Timestamp (8B).
Payload	N Bytes	Your actual sensor telemetry.
Signature	32 Bytes	The result of HMAC_SHA256(SecretKey, Header + Payload).

Implementation Example (Python)

import hmac
import hashlib
import struct
import time

# 1. Configuration
device_id = uuid.UUID('...').bytes
secret_key = bytes.fromhex('your_32_byte_hex_key')
payload = struct.pack('>hBBiiihb', temp, hum, bat, lat, lon, spd, rssi)

# 2. Add Timestamp (Big Endian)
timestamp = struct.pack('>Q', int(time.time()))

# 3. Calculate Signature
message = device_id + timestamp + payload
signature = hmac.new(secret_key, message, hashlib.sha256).digest()

# 4. Final Packet
packet = message + signature
# Send packet via UDP...

Best Practices

• Never Share Keys: Treat your HMAC keys as passwords. Never include them in your source code repository or share them over unencrypted channels.

• Unique Keys per Device: Do not use the same key for multiple devices. If one device is compromised, you only need to rotate its specific key.

• Synchronize Clocks: AdaTrack rejects packets with a timestamp difference greater than 5 seconds from the server time. Ensure your devices use an RTC or GPS-based time source.

• Constant-Time Comparison: When writing your own verification logic, always use constant-time comparison functions to prevent timing attacks.