HMAC

HMAC (Hash-based Message Authentication Code) is a method for verifying the authenticity and integrity of a message. It is widely used in API authentication and other security protocols. HMAC generates a unique code by combining the message with a secret key and a cryptographic hash function. The server recomputes the HMAC during verification; if the values match, the data is confirmed to be authentic and untampered.

Configurations

HMAC authentication mechanism has the following configurations:

Configuration	Description
Access Key	The unique identifier for the user or application.
Secret Key	The secret key, also known as the HMAC key, is a confidential cryptographic key used to generate and verify HMAC values. This key is shared between the sender and receiver.
Algorithm	Select from one of the following: HMAC SHA1 — Uses the SHA-1 hashing algorithm to generate an HMAC for verifying message authenticity and integrity. HMAC SHA 256 — Uses the SHA-256 hashing algorithm to produce a stronger, more secure HMAC for message verification. HMAC SHA 512 — Uses the SHA-512 hashing algorithm to generate a high-strength HMAC suitable for security-sensitive applications.
Signature header	The signature is commonly included in the `Authorization` header of an HTTP request. This approach is widely used to secure API endpoints when applying HMAC for authentication and data integrity verification.
Timestamp Header (Optional)	Including a timestamp header in HMAC authentication is a common practice that enhances security and helps prevent replay attacks. By adding a timestamp to the signed data, the server can validate that the request is recent and only accept it within a limited time window.
Canonical Request Format (Optional)	A canonical request format is a standardized way of representing an HTTP request before generating an HMAC (Hash-based Message Authentication Code) signature. It ensures that both the client and server process the request data in a consistent manner, allowing them to compute and verify the HMAC accurately.

Example

The following are some samples that you can use to configure the HMAC mechanism in the Advanced mode:

Sample 1

import hashlib
import hmac
import requests

def hmac_prehook(scanctx: ScanContext, pluginctx: PluginContext, testcase: TestCase, **kwargs) -> list[Assertion]:
    attributes = testcase.get_attributes()
    access_key = "your_access_key"
    secret_key = "your_secret_key"

    # set user
    normal_user = True
    bola_user = False

    request_url = attributes.get_one("mutated.http.request.url", default="")
    signature_header = "signature_header"
    payload = attributes.get_one("mutated.http.request.body", default="")
    hash_algorithm = hashlib.sha256
    interim_signature = hmac.new(secret_key.encode(), payload.encode(), hash_algorithm).hexdigest()
    hmac_signature = f'HMAC-SHA256 {access_key}:{interim_signature}'
    attributes.set("mutated.auth.attribute", "mutated.http.request.header." + signature_header)

    if normal_user:
        attributes.set("mutated.role.user", hmac_signature)
        attributes.set("mutated.http.request.header." + signature_header, hmac_signature)
    if bola_user:
        attributes.set("mutated.role.bolauser", hmac_signature)
    return []