Tutorial 31: Security Deep Dive - How OceanRemote Protects Your Devices

1. Security Overview: A 4‑Layer Defence

OceanRemote does not rely on a single “magic token”. Instead, every request must pass through four independent layers of verification. An attacker would have to compromise all four layers simultaneously to gain control of your device – a probability that approaches zero.

The diagram below shows how a legitimate command flows from your phone to the device, and where each security layer is applied.

2. The Four Layers Explained

2.1 Layer 1 – Account Authentication

Before you can even see your devices, you must log into your OceanRemote account. Passwords are hashed using Django’s PBKDF2 algorithm with 260,000 iterations (OWASP recommended). Accounts can be further protected by optional Two‑Factor Authentication (TOTP).

• Algorithm: PBKDF2 + SHA‑256
• Iterations: 260,000 (increases every year)
• 2FA support: Yes (Google Authenticator compatible)

2.2 Layer 2 – Token Validation (Registration + Permanent)

Every device receives a unique Registration Token during firmware generation. This token is:

• 256‑bits long → 2¹²⁸ possible combinations
• Valid for only 24 hours
• Invalidated immediately after first use

Once registered, the device is issued a Permanent Token that is stored in the device’s EEPROM with a 16‑bit checksum to detect corruption. This token is never sent over the network in plaintext; it is only used to establish a session.

// Token security parameters (from ESP32 firmware)
#define TOKEN_ADDRESS 0      // Stored in EEPROM
#define TOKEN_MAGIC 0xAA55   // Validation marker
#define TOKEN_LEN 32         // 256-bit keys
uint16_t checksum = 0;
for (int i = 0; i < len; i++) checksum += token[i];

2.3 Layer 3 – Session Management

After a device presents its Permanent Token, the server issues a short‑lived Session ID. This session rotates automatically and is never reused.

2.4 Layer 4 – MAC Address Binding

The strongest defence against token cloning. The Permanent Token is cryptographically bound to the device’s WiFi MAC address. Even if an attacker steals the token, they cannot use it from a different MAC address.

• MAC address is extracted during registration
• Every API call includes the device ID (derived from MAC)
• Server verifies that the token matches the MAC on every request

3. Quantitative Security Analysis

Let us calculate the probability that an attacker successfully takes control of a random OceanRemote device.

3.1 Assumptions

• Attacker has no prior knowledge (no stolen credentials).
• Attacker can make 100 requests per second (a very fast bot).
• We consider a 30‑day window (2.6 million seconds).

3.2 Step‑by‑Step Probability

4. Additional Security Mechanisms

4.1 Honeypot & Auto‑Ban

OceanRemote deploys a global honeypot that detects malicious scanning (e.g., attempts to access /admin, /wp-admin, /phpmyadmin). Any IP that triggers the honeypot is automatically banned for 24 hours.

• Failed attempts before ban: 20
• Ban duration: 24 hours (persistent across server restarts)
• Self‑unban page: /self-unban/ for legitimate users

4.2 Rate Limiting

Anonymous requests are limited to 20 per minute, authenticated users to 100 per minute. Device endpoints have no hard limit but are still subject to MAC binding checks.

4.3 Encrypted Communication

• All traffic forced over HTTPS (HSTS preload ready)
• Secure cookies (HttpOnly, SameSite=Lax)
• CSRF protection enabled on all state‑changing endpoints

4.4 Secure Firmware Generation

The firmware code you generate contains only the Registration Token and your WiFi credentials – no permanent secrets are embedded. The Registration Token is invalidated after first use, so even if the firmware file leaks, the token cannot be reused.

5. Defence in Depth – What If One Layer Fails?

Security is not about making a single layer perfect; it is about ensuring that no single failure leads to a breach. Here is what happens if each layer were hypothetically compromised:

6. Best Practices for Maximum Security

7. Summary