HMAC-256 Calculation


  1. Purpose This document establishes the normative HMAC signing and validation mechanism used in Kandupay. Its objective is to ensure authenticity, integrity, and protection against unauthorized access to the Gateway.

  2. Threat Model Covered • Manipulation of the request body or parameters.
    • Replay attacks within specific time windows.
    • Forwarding requests to different endpoints.
    • Impersonation of legitimate clients.

  3. Official Canonical String

    The canonical string is the deterministic representation of the request. It must be constructed identically on both the client and the server.


  4. Field Description

    _httpMethod: Protects the intent of the request (GET, POST, etc.).
    _path: Limits the validity of the signature to a specific endpoint.
    _queryString: Guarantees the integrity of parameters sent via URL.
    _payload: Protects the entire body against any alteration.
    _timestamp: Defines a valid time window.
    _nonce: Guarantees absolute uniqueness per request.

  5. Validation Flow (Sequence)

  6. Mandatory Implementation Rules

    • Always use the raw body for the signature.
    • Normalize the query string and HTTP method.
    • Use newline characters \n exclusively.
    • Do not allow partial signatures.

  7. Logging and Auditing Secrets, signatures, and full payloads must never be logged. For diagnostic purposes, logging hashes and metadata is permitted.

  8. Normative Status This document is normative. Any changes to the signing scheme require a security review and technical approval.