higress/plugins/wasm-go/extensions/replay-protection

title, keywords, description

title	keywords	description
Replay Attack Prevention	higress replay-protection	Configuration reference for the replay attack prevention plugin

Functional Description

The replay prevention plugin prevents request replay attacks by verifying the one-time random number in the request. Each request needs to carry a unique nonce value. The server will record and verify the uniqueness of this value, thus preventing requests from being maliciously replayed.

Specifically, it includes the following functions:

• Mandatory or Optional Nonce Verification: It can be configured to determine whether requests are required to carry a nonce value.
• Nonce Uniqueness Verification Based on Redis: The nonce value is stored and verified in Redis to ensure its uniqueness.
• Configurable Nonce Validity Period: It supports setting the validity period of the nonce, which will automatically expire after the period.
• Nonce Format and Length Verification: It supports verifying the format (Base64) and length of the nonce value.
• Custom Error Response: It supports configuring the status code and error message when a request is rejected.
• Customizable Nonce Request Header: The name of the request header carrying the nonce can be customized.

Runtime Attributes

Plugin execution stage: Authentication Stage Plugin execution priority: 800

Configuration Fields

Name	Data Type	Required	Default Value	Description
force_nonce	bool	No	true	Whether requests are required to carry a nonce value.
nonce_header	string	No	X-Higress-Nonce	Specifies the name of the request header carrying the nonce value.
nonce_ttl	int	No	900	The validity period of the nonce, in seconds.
nonce_min_length	int	No	8	The minimum length of the nonce value.
nonce_max_length	int	No	128	The maximum length of the nonce value.
reject_code	int	No	429	The status code returned when a request is rejected.
reject_msg	string	No	Replay Attack Detected	The error message returned when a request is rejected.
validate_base64	bool	No	false	Whether to verify the Base64 encoding format of the nonce.
redis	Object	Yes	-	Redis-related configuration

Description of each configuration field in redis

Name	Data Type	Required	Default Value	Description
service_name	string	Yes	-	The name of the Redis service, the complete FQDN name with the service type, such as my-redis.dns, redis.my-ns.svc.cluster.local.
service_port	int	No	6379	The port of the Redis service.
username	string	No	-	The username of Redis.
password	string	No	-	The password of Redis.
timeout	int	No	1000	The connection timeout time of Redis, in milliseconds.
database	int	No	0	The ID of the database to be used. For example, if it is configured as 1, it corresponds to SELECT 1.
key_prefix	string	No	replay-protection	The key prefix of Redis, used to distinguish different nonce keys.

Configuration Example

The following is a complete configuration example of the replay attack prevention plugin:

force_nonce: true
nonce_header: "X-Higress-Nonce"    # Specifies the name of the nonce request header
nonce_ttl: 900                    # The validity period of the nonce, set to 900 seconds
nonce_min_length: 8               # The minimum length of the nonce
nonce_max_length: 128             # The maximum length of the nonce
validate_base64: true             # Whether to enable Base64 format verification
reject_code: 429                  # The HTTP status code returned when a request is rejected
reject_msg: "Replay Attack Detected"  # The error message content returned when a request is rejected
redis:
  service_name: redis.static       # The name of the Redis service
  service_port: 80                # The port used by the Redis service
  timeout: 1000                   # The timeout time of Redis operations (unit: milliseconds)
  key_prefix: "replay-protection" # The key prefix in Redis

Usage Instructions

Request Header Requirements

Request Header Name	Required	Description
X-Higress-Nonce	Determined by the force_nonce configuration	The randomly generated nonce value carried in the request, which needs to conform to the Base64 format.

Note

: The name of the request header can be customized through the nonce_header configuration. The default value is X-Higress-Nonce.

Usage Example

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

Return Results

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

Error Response Examples

Error Scenario	Status Code	Error Message
Missing nonce request header	400	Missing Required Header
Nonce length does not meet the requirements	400	Invalid Nonce
Nonce format does not conform to Base64	400	Invalid Nonce
Nonce has been used (replay attack)	429	Replay Attack Detected