docs: hmac-auth body validation example should sign the Digest header
#13395 opened on May 20, 2026
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_stringis built from three lines only:{key_id}\n {request_method} {request_path}\n date: {gmt_time}\n - The
Authorizationheader listsheaders="@request-target date". - A
Digestheader (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:
- Compute the SHA-256 body digest first.
- Append
digest: SHA-256=<base64 body digest>\nto thesigning_string(lowercased key,<key>:<space><value>format, consistent with the existingdate:line). - Add
digestto theheaders="..."list in theAuthorizationheader, e.g.headers="@request-target date digest". - 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.