---
title: The Authentication Flow & Error Management
description: The Authentication Flow & Error Management
---
[Skip to content](https://portal.sandgrain.eu/knowledge-base/the-authentication-flow-error-management#main-content)
English
Show submenu for translations
.png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1).png)
Open main navigation
Close main navigation
- English
Show submenu for translations
- [Contact us](https://portal.sandgrain.eu/login)
[Contact us](https://portal.sandgrain.eu/login?hsLang=en)
How can we help you?
- There are no suggestions because the search field is empty.
1. [Knowledge Base](https://portal.sandgrain.eu/knowledge-base?hsLang=en)
2. [User Documentation](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en)
3. [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#sandgrain-sdk)
October 6, 2026
# The Authentication Flow & Error Management
**Who this is for:** Developers who need to understand exactly what happens during a device authentication, including the fault-tolerant path.
**What you'll learn:** The step-by-step sequence the Gateway drives, and how Error Management recovers from a noisy channel.
In the proof of concept, the Gateway drives the device-authentication flow, with the Cloud SDK agent and CyberRock acting as the Server.
> ****
>
>
> Phase 1, Token-to-Server device authentication (requestCW / replyRW / checkAuthStatus, with Error Management).
### The sequence
1. **Receive auth request.** The Gateway receives the request (with the device identifier) and resolves it against the `auth_db` to retrieve the Token ID. An unregistered device fails with `SGR_SDK_NOT_REGISTERED`.
2. **Request challenge.** The Gateway asks CyberRock to generate the Challenge Word (CW) for the device's TID via MQTT `requestCW`, then relays the CW to the Device (`gw_log 2/6`, then `3/6`).
3. **Device response.** The Device's crypto chip computes a Response Word (RW) and returns it together with the CW echo (`gw_log 4/6`).
4. **Verify CW echo.** The Gateway compares the original CW against the echo. If the difference exceeds `CW_BITFLIP_THRESHOLD`, authentication fails immediately; otherwise candidate CWs are prepared in case Error Management is needed.
5. **Decide (clean path).** When the CW echo matches the original, the Gateway forwards the RW to CyberRock via MQTT `replyRW`. CyberRock returns `AUT_OK`, `CLAIM_TOKEN` (with a `claim_token_id` that TrustBridge auto-claims), or `AUT_NOK` (`gw_log 5/6`, then `6/6`).
6. **Error Management (noisy path).** If the CW echo differed but stayed within `CW_BITFLIP_THRESHOLD`, the Gateway builds candidate CWs and, for each, asks CyberRock for that candidate's RW via MQTT `requestRW`, comparing it locally against the Device RW within `RW_BITFLIP_THRESHOLD`.
7. **Resolution.** The first candidate that matches within threshold yields `AUT_OK`. If all candidates are exhausted (or the CW echo differed beyond `CW_BITFLIP_THRESHOLD`), authentication fails with `AUT_NOK`.
8. **Send result.** `AUT_OK` / `AUT_NOK` is returned to the Device and recorded in the `auth_db`. On failure the state machine resets and waits for a new request.
> ****
>
> Phase 2, Server-to-Token mutual verification (requestRW maps CW to HCW, RW to HRW).
### How Error Management works, in plain terms
A noisy channel can flip a few bits in transit. Rather than rejecting a genuine device over noise, the Gateway reconstructs up to seven **candidate CWs** by flipping combinations of the bits that were seen to differ, then asks the Server to compute the RW for each candidate one at a time, checking each against the device's RW until one matches or all are exhausted.
- If any comparison (direct or via a candidate) matches within tolerance, the device is authenticated (`AUT_OK`).
- If nothing matches (the corruption was too severe upfront, or every candidate failed), the device is rejected (`AUT_NOK`).
The same fault-tolerant compare logic runs identically whether it's the initial claim or a later re-authentication; only the trigger differs.
### Firmware verification and installation
Firmware verification is SandGrain's way of proving that a firmware image is genuine and untampered before the device is ever allowed to install it. Instead of relying on software-only signatures, it reuses the same hardware challenge-response mechanism as device authentication: the answer can only come from the physical crypto chip (the Token), so a tampered image or a cloned device can't fake approval.
**How the sequence works**
1. **Hash the image.** The device computes a SHA-256 hash of the firmware image (fw\_data, fw\_size).
2. **Chip signs the hash.** The device's crypto chip takes that hash and derives a Response Word (RW) from it using its embedded secret - effectively a hardware signature over the firmware. The secret never leaves the chip.
3. **Send to the server**. The device calls SGR\_SDK\_Verification\_FW(fw\_data, fw\_size, fw\_rw); the RW travels through the Gateway (which routes it via its dispatcher, SGR\_SDK\_GW\_Handle\_FW\_Verification) and up to the cloud over the MQTT fwVerification request to CyberRock.
4. **Server verdict.** The server validates the RW and returns FW\_OK (genuine, correctly signed image) or FW\_NOK (tampered or unsigned image → the SDK returns SGR\_SDK\_AUTH\_FAILED).
5. **Save RW\_verify.** On success, the computed RW is kept as RW\_verify. This value is the ticket for the next step.
> ****
>
>
> Firmware verification and installation (SGR\_SDK\_Verification\_FW then SGR\_SDK\_Installation).
**Why it gates installation**
Verification and installation are deliberately two separate, chained steps:
- SGR\_SDK\_Installation() sends the saved RW\_verify (concatenated with itself, per the protocol) plus the device credentials to the server, which grants or denies installation authorization (MQTT fwInstallation).
- Installation is only authorized if a successful verification happened earlier in the same session — the RW\_verify must not be discarded between the two calls. Skipping verification, or attempting installation after an FW\_NOK, is denied with FW\_INSTALL\_NOT\_ALLOWED and a final status of AUTH\_FAILED.
Firmware verification hashes the image (SHA-256), obtains the expected RW from the crypto chip, and compares. A tampered or unsigned image yields `FW_NOK`, and installation is then denied with `FW_INSTALL_NOT_ALLOWED` and a final status of `AUTH_FAILED`. Verification must succeed in the same session before installation is authorized.
---
*Related articles: [Developer Guide & Best Practices](https://portal.sandgrain.eu/knowledge-base/developer-guide-best-practices?hsLang=en) · [MQTT Topic Reference](https://portal.sandgrain.eu/knowledge-base/mqtt-topic-reference?hsLang=en) · [SDK API Reference](https://portal.sandgrain.eu/knowledge-base/sdk-api-reference?hsLang=en) · [Compile-Time Configuration](https://portal.sandgrain.eu/knowledge-base/compile-time-configuration-sdk-sgr-config.h?hsLang=en)*
- [User Documentation](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#main-content)
- [Quick Starter Guide](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#quick-starter-guide)
- [User Manual](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#user-manual)
- [Whitepaper](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#whitepaper)
- [Token Leaflet](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#token-leaflet)
- [Claim Token Procedure](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#claim-token-procedure)
- [Daisy Chain](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#daisy-chain)
- [Release Note](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#release-note)
- [Naming Convention](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#naming-convention)
- [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#sandgrain-sdk)
- [TrustBridge](https://portal.sandgrain.eu/knowledge-base/user-documentation?hsLang=en#trustbridge)
- [API Documentation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#main-content)
- [Device API Integration](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#device-api-integration)
- [Daisy Chain and Attestation](https://portal.sandgrain.eu/knowledge-base/api-documentation?hsLang=en#daisy-chain-and-attestation)
- [SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#main-content)
- [Core Functions](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#core-functions)
- [SandGrain SDK](https://portal.sandgrain.eu/knowledge-base/sdk?hsLang=en#sandgrain-sdk)
[-1.png?width=427&height=83&name=SandGrain_Logo_RGB_white-bijgesneden%20(1)-1.png "SandGrain_Logo_RGB_white-bijgesneden (1)-1")](https://portal.sandgrain.eu/?hsLang=en)
[mailto:email@email.com](mailto:email@email.com)
Copyright © 2026, sandgrain.eu