Dictionary Attack in Fastapi with Hmac Signatures

A dictionary attack against an API that uses HMAC signatures in FastAPI can occur when the service does not adequately protect the signing process or the way it validates incoming requests. HMAC is designed to ensure integrity and authenticity: the client computes a signature using a shared secret and the request payload or selected headers, and the server recomputes the signature and compares it in a time‑constant manner. If the server leaks information about whether a signature is close to valid—through timing differences, error messages, or behavior changes—an attacker can use that feedback to iteratively guess credentials or tokens.

In FastAPI, common mistakes that enable dictionary attacks include using a non‑constant‑time comparison for the signature, exposing whether a request was missing or malformed in a way that differs from a bad signature, and accepting requests with ambiguous or overly permissive content types. For example, if the endpoint first checks for the presence of a signature header and returns a distinct error before performing the HMAC verification, an attacker can learn which requests contain a valid signature structure. Repeated requests with slightly altered payloads or guessed tokens can allow an attacker to build a dictionary of valid signatures or to recover the shared secret when weak randomness or predictable keys are involved.

Consider a FastAPI endpoint that expects an HMAC‑SHA256 signature in a custom header and uses the request body as the signing string. If the server does not enforce strict content‑type handling and normalizes inputs inconsistently, an attacker can submit many variants and observe differences in response codes or latency. This behavior can be combined with known weaknesses in the secret management pipeline (e.g., hardcoded or poorly rotated secrets) to mount a practical dictionary or brute‑force attack. Even when the server eventually returns a generic error, subtle timing differences—such as the time taken to parse JSON, validate structure, and compute the HMAC—can allow an adaptive attacker to infer when a signature computation path is partially correct.

Because FastAPI relies on Pydantic models for request parsing, additional risks arise if the schema validation is performed before signature verification or if validation errors produce distinct messages. An attacker can probe the API with malformed payloads to learn which fields are required, which data types are accepted, and whether certain patterns in the signature header trigger different code paths. Over time, this can resemble a dictionary attack against the signing scheme, especially when combined with predictable key material or insufficient entropy in token generation.

To mitigate dictionary attacks against HMAC‑based authentication in FastAPI, implement constant‑time signature verification, strict input handling, and clear separation between validation and authentication logic. Below is a concise, production‑oriented example that demonstrates how to securely verify HMAC signatures in FastAPI.

import time
import hmac
import hashlib
import secrets
from fastapi import FastAPI, Header, HTTPException, Request
from typing import Optional

app = FastAPI()

# Use a strong, randomly generated secret stored securely (e.g., env, vault)
SHARED_SECRET = secrets.token_bytes(32)

def verify_hmac_signature(body: bytes, received_signature: str) -> bool:
    """Verify HMAC‑SHA256 using a constant‑time comparison."""
    expected_signature = hmac.new(SHARED_SECRET, body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected_signature, received_signature)

@app.post("/secure-endpoint")
async def secure_endpoint(
    request: Request,
    x_api_signature: Optional[str] = Header(None, alias="X-API-Signature")
):
    # Read raw body once; ensure consistent behavior regardless of validation outcome
    try:
        body = await request.body()
    except Exception:
        raise HTTPException(status_code=400, detail="Unable to read request body")

    # Require signature for all requests; do not leak reasons for failure
    if x_api_signature is None:
        raise HTTPException(status_code=401, detail="Unauthorized")

    # Constant‑time verification to prevent timing leaks
    if not verify_hmac_signature(body, x_api_signature):
        raise HTTPException(status_code=401, detail="Unauthorized")

    # Only after successful verification proceed to business logic / Pydantic parsing
    try:
        payload = request.json()  # or use a Pydantic model with request.json()
    except Exception:
        raise HTTPException(status_code=400, detail="Invalid JSON")

    return {"status": "ok", "data": payload}

Key practices reflected in this code:

• Use hmac.compare_digest for signature comparison to avoid timing attacks.
• Read the raw request body before any schema validation to ensure the same code path is followed for valid and invalid signatures.
• Return a uniform error response for missing or invalid signatures to prevent information leakage.
• Generate the shared secret with sufficient entropy and rotate it according to your operational security policy.
• Enforce strict content‑type handling and validate input after authentication to reduce side‑channel information.

Beyond code, complement this with operational measures: rotate HMAC secrets periodically, monitor for high rates of authentication failures from single sources, and integrate middleBrick scans to detect misconfigurations in your FastAPI endpoints. The CLI makes it easy to include checks in scripts—run middlebrick scan <url> to identify authentication and integrity issues early. For teams that need continuous coverage, the Pro plan provides automated scanning and alerts, while the GitHub Action can fail builds if a security score drops below your chosen threshold.