apache/apisix

docs: hmac-auth body validation example should sign the Digest header

Open

#13395 opened on May 20, 2026

View on GitHub
 (0 comments) (0 reactions) (0 assignees)Lua (16,597 stars) (2,860 forks)batch import
docgood first issue

Description

Description

This is a small, self-contained documentation improvement for the hmac-auth plugin docs.

File: docs/en/latest/plugins/hmac-auth.md Location: the body-validation example block (hmac-sig-digest-header-gen.py, currently around lines 871-921).

Current example

The example demonstrates the validate_request_body: true configuration. In the Python helper:

  • The signing_string is built from three lines only:
    {key_id}\n
    {request_method} {request_path}\n
    date: {gmt_time}\n
    
  • The Authorization header lists headers="@request-target date".
  • A Digest header (SHA-256=<base64 body digest>) is computed and sent in the request.

So the Digest header is sent, but it never appears in the signed headers="..." list and is not part of the signing_string. As written, the example produces a setup where the Digest header is not bound to the HMAC signature.

Why this is worth fixing

A reader copying this example as a starting point for body validation ends up with an example that is incomplete and slightly misleading: it looks like it demonstrates end-to-end body integrity, but the Digest header it sends is not actually covered by the signature. The example should reflect the intended usage, where the body digest is part of what gets signed.

Proposed fix

Update the example so it signs the Digest header:

  1. Compute the SHA-256 body digest first.
  2. Append digest: SHA-256=<base64 body digest>\n to the signing_string (lowercased key, <key>:<space><value> format, consistent with the existing date: line).
  3. Add digest to the headers="..." list in the Authorization header, e.g. headers="@request-target date digest".
  4. Update the printed example output accordingly.

It would also help to add a short note in the prose explaining that validate_request_body only checks the Digest header against the request body, so operators who want the body itself bound to the signature should also include the Digest header in the signed headers list (or enforce it via the signed_headers config option).

Good first issue

This is a good first issue: it is a small, contained docs-only change to a single example block plus a short prose note. No code changes are required.

Contributor guide