Peer

Defines a WireGuard peer configuration for authentication and network access control. Each peer represents an authorized client that can establish encrypted connections to a WireGuard listener.

Syntax

To declare this entity in your AWS CloudFormation template, use the following syntax:

JSON

{
  "PublicKey" : String,
  "AllowedIPs" : [ String, ... ],
  "SharedSecret" : String
}
    

YAML

PublicKey: String
AllowedIPs: [ String, ... ]
SharedSecret: String
    

Properties

PublicKey

The base64-encoded WireGuard public key for this peer. This is a 32-byte Curve25519 public key generated by the client using wg genkey | wg pubkey or equivalent. This key is used to authenticate the peer and establish encrypted communication.

Required: Yes

Type: String

Update requires: No interruption

AllowedIPs

A list of IP address ranges (in CIDR notation) that this peer is allowed to send traffic from. This provides network-level access control within the WireGuard tunnel. If not specified, the peer can send traffic from any IP address within the tunnel.

Required: No

Type: List of String

Update requires: No interruption

SharedSecret

An optional base64-encoded 32-byte pre-shared key (PSK) that provides an additional layer of security through symmetric encryption. The PSK is combined with the key exchange to provide post-quantum security resistance. Both the peer and the listener must be configured with the same SharedSecret value.

Required: No

Type: String

Update requires: No interruption

Examples

Basic Peer Configuration

YAML

- PublicKey: "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg="
  AllowedIPs:
  - "10.0.0.2/32"
    

JSON

{
  "PublicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
  "AllowedIPs": [
    "10.0.0.2/32"
  ]
}
    

Peer with Pre-Shared Key

YAML

- PublicKey: "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg="
  AllowedIPs:
  - "10.0.0.2/32"
  - "10.0.1.0/24"
  SharedSecret: "FpCyhws9cxwWoV4xELtfJvjJN+zQVRPISllRWgM="
    

JSON

{
  "PublicKey": "xTIBA5rboUvnH4htodjb6e697QjLERt1NAB4mZqp8Dg=",
  "AllowedIPs": [
    "10.0.0.2/32",
    "10.0.1.0/24"
  ],
  "SharedSecret": "FpCyhws9cxwWoV4xELtfJvjJN+zQVRPISllRWgM="
}
    

Remarks

Key Generation

WireGuard keys can be generated using the wg command-line tool:

# Generate private key
wg genkey > private.key

# Generate public key from private key
wg pubkey < private.key > public.key

# Generate pre-shared key (optional)
wg genpsk > preshared.key
    

AllowedIPs Considerations

The AllowedIPs property serves as an access control mechanism within the WireGuard tunnel:

• Use specific IP addresses (10.0.0.2/32) for single-client identification
• Use broader ranges (10.0.0.0/24) for clients that may have multiple addresses
• Leave empty to allow traffic from any IP within the tunnel (less secure but more flexible)
• Multiple ranges can be specified for complex network topologies

Security Best Practices

• Generate unique key pairs for each peer - never share private keys
• Use pre-shared keys (SharedSecret) for enhanced security, especially in high-security environments
• Restrict AllowedIPs to the minimum necessary IP ranges for each peer
• Rotate keys periodically according to your security policy
• Store private keys securely and never include them in CloudFormation templates