apache / apache/apisix

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

Open Beginner friendly
#13,395 2 comments 0 reactions 0 assignees View on GitHub
doc good first issue
Dominant language
Lua
Stars
17.1k
Forks
2.9k
Avg merge
3d 16h
Merged PRs (30d)
63

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=`) 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=\n` to the `signing_string` (lowercased key, `:` 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

Open the contributing guide

Research direction

Open docs/en/latest/plugins/hmac-auth.md and inspect the body-validation example around hmac-sig-digest-header-gen.py, including its printed output. Update the example and nearby prose so the Digest header is included in the signing string and signed headers list, and verify the displayed output matches the revised example.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.