---
title: 防重放攻击
keywords: [higress,replay-protection]
description: 防重放攻击插件配置参考
---

## 功能说明

防重放插件通过验证请求中的一次性随机数来防止请求重放攻击。每个请求都需要携带一个唯一的 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 键 |

## 配置示例

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

```yaml
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`。

### 使用示例

```bash
# 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"}'
```

## 返回结果

```json
{
  "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` |