feat(hmac-auth): default signed_headers to ["date"] (#13388)

Author: shreemaan-abhishek

apisix/plugins/hmac-auth.lua

@@ -51,6 +51,7 @@ local schema = {
         },
         signed_headers = {
             type = "array",
+            default = {"date"},
             items = {
                 type = "string",
                 minLength = 1,
@@ -232,15 +233,10 @@ local function validate(ctx, conf, params)
     -- validate headers
     -- All headers passed in route conf.signed_headers must be used in signing(params.headers)
     if conf.signed_headers and #conf.signed_headers >= 1 then
-        if not params.headers then
-            return nil, "headers missing"
-        end
-        local params_headers_map = array_to_map(params.headers)
-        if params_headers_map then
-            for _, header in ipairs(conf.signed_headers) do
-                if not params_headers_map[header] then
-                    return nil, [[expected header "]] .. header .. [[" missing in signing]]
-                end
+        local params_headers_map = params.headers and array_to_map(params.headers) or {}
+        for _, header in ipairs(conf.signed_headers) do
+            if not params_headers_map[header] then
+                return nil, [[expected header "]] .. header .. [[" missing in signing]]
             end
         end
     end

docs/en/latest/plugins/hmac-auth.md

@@ -63,8 +63,8 @@ The following attributes are available for configurations on Routes or Services.
 | Name                  | Type          | Required | Default                                      | Valid values                                                              | Description                                                                                                                                                                                                                                                                                                                                          |
 |-----------------------|---------------|----------|----------------------------------------------|---------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | allowed_algorithms    | array[string] | False    | `["hmac-sha1", "hmac-sha256", "hmac-sha512"]` | Combination of `"hmac-sha1"`, `"hmac-sha256"`, and `"hmac-sha512"`       | The list of HMAC algorithms allowed.                                                                                                                                                                                                                                                                                                                 |
-| clock_skew            | integer       | False    | 300                                          | >=1                                                                       | Maximum allowable time difference in seconds between the client request's timestamp and APISIX server's current time. This helps account for discrepancies in time synchronization between the client's and server's clocks and protect against replay attacks. The timestamp in the `Date` header (must be in GMT format) will be used for the calculation. |
-| signed_headers        | array[string] | False    |                                              |                                                                           | The list of HMAC-signed headers that should be included in the client request's HMAC signature.                                                                                                                                                                                                                                                      |
+| clock_skew            | integer       | False    | 300                                          | >=1                                                                       | Maximum allowable difference in seconds between the value of the request's `Date` header (which must be in GMT format) and APISIX's current time. This helps reject stale requests when the client and server clocks are reasonably in sync. For the freshness window to be meaningful, `date` must be part of `signed_headers` so that the `Date` value is bound into the signing string. With the default `signed_headers` value of `["date"]`, this binding is in place out of the box. |
+| signed_headers        | array[string] | False    | `["date"]`                                   |                                                                           | The list of headers that must be included in the client request's HMAC signing string. The default value of `["date"]` ensures the `Date` header is always bound into the signing string, so that the value used for the `clock_skew` freshness check is itself covered by the HMAC. Set this explicitly to override the headers that must be signed; setting it to an empty array `[]` removes the requirement entirely. |
 | validate_request_body | boolean       | False    | false                                        |                                                                           | If true, validate the integrity of the request body to ensure it has not been tampered with during transmission. Specifically, the Plugin creates a SHA-256 base64-encoded digest and compares it to the `Digest` header. If the `Digest` header is missing or if the digests do not match, the validation fails.                                     |
 | hide_credentials      | boolean       | False    | false                                        |                                                                           | If true, do not pass the authorization request header to Upstream services.                                                                                                                                                                                                                                                                          |
 | anonymous_consumer    | string        | False    |                                              |                                                                           | Anonymous Consumer name. If configured, allow anonymous users to bypass the authentication.                                                                                                                                                                                                                                                          |

docs/zh/latest/plugins/hmac-auth.md

@@ -64,8 +64,8 @@ import TabItem from '@theme/TabItem';
 | 名称                  | 类型          | 必选项 | 默认值                                         | 有效值                                                              | 描述                                                                                                                                                                                                                                                                                                                                                    |
 |-----------------------|---------------|--------|------------------------------------------------|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | allowed_algorithms    | array[string] | 否     | `["hmac-sha1", "hmac-sha256", "hmac-sha512"]`  | `"hmac-sha1"`、`"hmac-sha256"` 和 `"hmac-sha512"` 的组合           | 允许的 HMAC 算法列表。                                                                                                                                                                                                                                                                                                                                   |
-| clock_skew            | integer       | 否     | 300                                            | >=1                                                                 | 客户端请求的时间戳与 APISIX 服务器当前时间之间允许的最大时间差（以秒为单位）。这有助于解决客户端和服务器之间的时间同步差异，并防止重放攻击。时间戳将根据 `Date` 头中的时间（必须为 GMT 格式）进行计算。                                                                                                                                                  |
-| signed_headers        | array[string] | 否     |                                                |                                                                     | 客户端请求的 HMAC 签名中应包含的标头列表。                                                                                                                                                                                                                                                                                                               |
+| clock_skew            | integer       | 否     | 300                                            | >=1                                                                 | 请求的 `Date` 头（必须为 GMT 格式）与 APISIX 当前时间之间允许的最大时间差（秒）。该机制用于在客户端与服务端时钟基本同步的前提下拒绝过期请求。要使该时效窗口具有实际意义，`date` 必须出现在 `signed_headers` 中，从而将 `Date` 的取值绑定进签名字符串。`signed_headers` 默认值为 `["date"]`，开箱即默认完成该绑定。                                                                            |
+| signed_headers        | array[string] | 否     | `["date"]`                                     |                                                                     | HMAC 签名字符串中必须包含的请求头列表。默认值为 `["date"]`，确保 `Date` 头始终被绑定进签名字符串，使得 `clock_skew` 时效校验所依据的取值同样受 HMAC 覆盖。如需覆盖默认值，请显式设置该字段；设置为空数组 `[]` 则完全取消该要求。                                                                                                                                                              |
 | validate_request_body | boolean       | 否     | false                                          |                                                                     | 如果为 true，则验证请求正文的完整性，以确保在传输过程中没有被篡改。具体来说，插件会创建一个 SHA-256 的 base64 编码 digest，并将其与 `Digest` 头进行比较。如果 `Digest` 头丢失或 digest 不匹配，验证将失败。                                                                                                                                                |
 | hide_credentials      | boolean       | 否     | false                                          |                                                                     | 如果为 true，则不会将授权请求头传递给上游服务。                                                                                                                                                                                                                                                                                                          |
 | anonymous_consumer    | string        | 否     |                                                |                                                                     | 匿名 Consumer 名称。如果已配置，则允许匿名用户绕过身份验证。                                                                                                                                                                                                                                                                                             |