防重放攻击

功能说明

防重放插件通过验证请求中的一次性随机数来防止请求重放攻击。每个请求都需要携带一个唯一的 nonce 值，服务器会记录并校验这个值的唯一性，从而防止请求被恶意重放

具体包含一下功能：

强制或可选的 nonce 校验：可根据配置决定是否强制要求请求携带 nonce 值。
基于 Redis 的 nonce 唯一性验证：通过 Redis 存储和校验 nonce 值，确保其唯一性。
可配置的 nonce 有效期：支持设置 nonce 的有效期，过期后自动失效。
nonce 格式和长度校验：支持对 nonce 值的格式（Base64）和长度进行验证。
自定义错误响应：支持配置拒绝请求时的状态码和错误信息。
可自定义 nonce 请求头：可以自定义携带 nonce 的请求头名称。

运行属性

插件执行阶段：认证阶段 插件执行优先级：800

配置字段

名称	数据类型	必填	默认值	描述
`force_nonce`	bool	否	true	是否强制要求请求携带 nonce 值
`nonce_header`	string	否	`X-Higress-Nonce`	指定携带 nonce 值的请求头名称
`nonce_ttl`	int	否	900	nonce 的有效期，单位秒
`nonce_min_length`	int	否	8	nonce 值的最小长度
`nonce_max_length`	int	否	128	nonce 值的最大长度
`reject_code`	int	否	429	拒绝请求时返回的状态码
`reject_msg`	string	否	`Replay Attack Detected`	拒绝请求时返回的错误信息
`validate_base64`	bool	否	false	是否校验 nonce 的 base64 编码格式
`redis`	Object	是	-	redis 相关配置

redis 中每一项的配置字段说明

名称	数据类型	必填	默认值	描述
`service_name`	string	是	-	redis 服务名称，带服务类型的完整 FQDN 名称，例如 my-redis.dns、redis.my-ns.svc.cluster.local
`service_port`	int	否	6379	redis 服务端口
`username`	string	否	-	redis 用户名
`password`	string	否	-	redis 密码
`timeout`	int	否	1000	redis 连接超时时间，单位毫秒
database	int	否	0	使用的数据库id，例如配置为1，对应`SELECT 1`
`key_prefix`	string	否	`replay-protection`	redis 键前缀，用于区分不同的 nonce 键

配置示例

以下是一个防重放攻击插件的完整配置示例：

force_nonce: true
nonce_header: "X-Higress-Nonce"    # 指定 nonce 请求头名称
nonce_ttl: 900                    # nonce 有效期，设置为 900 秒
nonce_min_length: 8               # nonce 的最小长度
nonce_max_length: 128             # nonce 的最大长度
validate_base64: true             # 是否开启 base64 格式校验
reject_code: 429                  # 当拒绝请求时返回的 HTTP 状态码
reject_msg: "Replay Attack Detected"  # 拒绝请求时返回的错误信息内容
redis:
  service_name: redis.static       # Redis 服务的名称
  service_port: 80                # Redis 服务所使用的端口
  timeout: 1000                   # Redis 操作的超时时间（单位：毫秒）
  key_prefix: "replay-protection" # Redis 中键的前缀

使用说明

请求头要求

请求头名称	是否必须	说明
`X-Higress-Nonce`	根据 `force_nonce` 配置决定	请求中携带的随机生成的 nonce 值，需符合 Base64 格式。

注意：可以通过 nonce_header 配置自定义请求头名称，默认值为 X-Higress-Nonce。

使用示例

# Generate nonce
nonce=$(openssl rand -base64 32)

# Send request
curl -X POST 'https://api.example.com/path' \
  -H "X-Higress-Nonce: $nonce" \
  -d '{"key": "value"}'

返回结果

{
  "code": 429,
  "message": "Replay Attack Detected"
}

错误响应示例

错误场景	状态码	错误信息
缺少 nonce 请求头	400	`Missing Required Header`
nonce 长度不符合要求	400	`Invalid Nonce`
nonce 格式不符合 Base64	400	`Invalid Nonce`
nonce 已被使用（重放攻击）	429	`Replay Attack Detected`