HMAC 256 - blokko-signature

Purpose

This document establishes the normative mechanism for HMAC signature and validation used in Blokko. Its objective is to guarantee authenticity, integrity, and protection against replay attacks in all critical APIs.

Threat Model Covered

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

Official Canonical String

The canonical string is the deterministic representation of the request. It must be built exactly the same on the client and server.

{httpMethod}\n{path}\n{queryString}\n{payload}\n{timestamp}\n{nonce}

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 complete body against any alteration.
• timestamp: Defines a valid time window.
• nonce: Guarantees absolute uniqueness per request.

Validation Flow (Sequence)

1. Client generates the Canonical String.
2. Signed request is sent (headers + body).
3. Blokko API receives the request.
4. Validate minimum headers.
5. Validate HMAC.
6. Validate timestamp.
7. Validate nonce (cache TTL).
8. Validate payload model.
9. Process request.

Mandatory Implementation Rules

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

Logging and Auditing

Secrets, signatures, or full payloads must never be logged. For diagnostics, registering hashes and metadata is allowed.

Normative Character

This document is normative. Any change to the signature scheme requires security review and technical approval.

Header Implementation

To successfully authenticate, the resulting payload values must be wrapped inside a single HTTP header named blokko-signature. The value of this header must be formatted as a single continuous string containing the API key, timestamp, nonce, and the calculated HMAC signature, separated by commas.

Format structure:

blokko-signature: Api-Key={apiKey}, Timestamp={timestamp}, Nonce={nonce}, Signature={signature}