Manages a dedicated listener with an assigned port on an Proxylity ingress domain, the properties of the listener, and the destinations associated with it.
To declare this entity in your AWS CloudFormation template, use the following syntax:
{
"Type" : "Custom::ProxylityUdpGatewayListener",
"Properties" : {
"ServiceToken" : String,
"ApiKey" : String,
"Protocols" : [ String, ... ],
"Peers" : [ Peer, ... ],
"DecapsulatedDelivery" : Boolean,
"AllowUnknownPeers" : Boolean,
"UnknownPeerPreSharedKey" : String,
"RequireCookies" : String,
"Psks" : Object,
"AllowEarlyData" : String,
"EarlyDataWindowSeconds" : String,
"CertRefreshToken" : String,
"Destinations" : [ Destination, ... ],
"ClientRestrictions" : [ ClientRestriction, ... ]
}
}
Type: Custom::ProxylityUdpGatewayListener
Properties:
ServiceToken: String
ApiKey: String
Protocols: [ String, ... ]
Peers: [ Peer, ... ]
DecapsulatedDelivery: Boolean
AllowUnknownPeers: Boolean
UnknownPeerPreSharedKey: String
RequireCookies: String
Psks: Object
AllowEarlyData: String
EarlyDataWindowSeconds: String
CertRefreshToken: String
Destinations: [ Destination, ... ]
ClientRestrictions: [ ClientRestriction, ... ]
The ARN of the Proxylity custom resource handler in the deployment region found in the customer configuration provided by Proxylity. See AWS::Cloudformation::CustomResource.
The ApiKey provided to you by Proxylity.
The transport protocol the listener supports. Specify exactly one value: udp for standard UDP,
dtls for DTLS 1.2 and DTLS 1.3, or wg for WireGuard.
Required: Yes
Type: List of String
Update requires: No interruption
Specifies the WireGuard peer configurations. This property is only valid for WireGuard listeners (when Protocols contains 'wg'). Each peer defines cryptographic keys and network access controls for authenticated WireGuard clients.
Required: No (only valid for WireGuard listeners)
Type: List of Peer
Update requires: No interruption
When set to true on a WireGuard Listener, the Gateway strips the WireGuard tunnel headers before
delivering packets to Destinations. Each Destination receives the original inner UDP payload — identical to
what a plain UDP Listener would deliver — plus an Inner metadata block in the JSON envelope
containing the inner IP addressing (source/destination address and port, protocol number, and IP version)
from inside the tunnel.
Enabling Decapsulated Delivery allows WireGuard Listeners and plain UDP Listeners to share the same Destinations, since the delivered payload format is identical. This property has no effect on plain UDP Listeners.
Required: No
Type: Boolean
Update requires: No interruption
For full details and examples, see Now Available: Decapsulated Delivery for WireGuard Listeners.
When set to true on a WireGuard Listener, the Gateway accepts connections from any WireGuard peer,
not just those explicitly listed in the Peers property. This enables public-endpoint scenarios
analogous to HTTPS for websites: any client with a WireGuard keypair can connect without pre-registration,
and the connection is still fully encrypted. This is useful for public-facing services, large device fleets,
and dynamic environments where enumerating every peer public key in advance is impractical.
When AllowUnknownPeers is enabled, all peers — both listed and unlisted — share the same
Destinations. To add a shared credential gate for unknown peers, configure
UnknownPeerPreSharedKey with a secret that all connecting clients must include in their
WireGuard configuration.
Required: No
Type: Boolean
Default: false
Update requires: No interruption
A base64-encoded 32-byte pre-shared key (PSK) applied to all unknown peers when
AllowUnknownPeers is true. Peers explicitly listed in the Peers
property use the SharedSecret defined on each individual peer entry and are unaffected by this
property.
The PSK provides a symmetric authentication layer on top of the Curve25519 key exchange, giving you a degree of
access control even when public keys are not pre-registered. Clients that do not present the correct PSK will
fail the WireGuard handshake. This property has no effect when AllowUnknownPeers is
false.
Required: No
Type: String (base64-encoded 32 bytes)
Update requires: No interruption
When set to "true" on a DTLS Listener, clients must complete a DTLS cookie exchange before the full
handshake. This helps reduce amplification and resource-exhaustion risk for public endpoints.
Required: No (only valid for DTLS listeners)
Type: String containing a Boolean value
Default: "false"
Update requires: No interruption
A map of DTLS-PSK client identities to base64-encoded pre-shared keys. Each connecting PSK client sends one of the configured identities during its handshake. Store values in AWS Secrets Manager or another protected source rather than committing them to the template.
Required: No (only valid for DTLS listeners)
Type: Object with non-empty String values
Default: Empty object
Update requires: No interruption
An arbitrary value used to rotate a DTLS Listener's managed server certificate. Changing, adding, or removing the value generates a new certificate and private key. Coordinate client trust updates before changing this property on a production Listener.
Required: No (only used by DTLS listeners)
Type: String
Update requires: No interruption
When set to "true", a resumed DTLS 1.3 client may send application data in its first flight. Enable
this only when the Destination treats requests as idempotent and safe to replay. This property does not apply to
DTLS 1.2.
Required: No (only valid for DTLS listeners)
Type: String containing a Boolean value
Default: "false"
Update requires: No interruption
The DTLS 1.3 session-ticket lifetime and shared 0-RTT replay-filter window, in seconds. Valid values are 1 through 604800 (seven days).
Required: No (only valid for DTLS listeners)
Type: String containing an integer
Default: "3600"
Update requires: No interruption
For configuration examples and client guidance, see DTLS Listeners.
Specifies the AWS resources that will be used to handle packets arriving at the Listener.
Required: No
Type: List of Destination
Update requires: No interruption
Specifies the IP addresses (in CIDR format) and domains (CPF DNS lookup) for which traffic will be accepted. Not
including the ClientRestrictions property causes all traffic to be blocked. It's highly recommended
to include only trusted networks of IPs as allowed senders for your listeners.
Required: No
Type: List of ClientRestriction
Update requires: No interruption
When you pass the logical ID of this resource to the intrinsic Ref function, Ref returns the Id.
The Fn::GetAtt intrinsic function returns a value for a specified attribute of this type. The
following are the available attributes and sample return values.
For more information about using the Fn::GetAtt intrinsic function, see Fn::GetAtt.
The logical ID assigned when the resource is created.
The port assigned to the listener. Send traffic to this port on one of the assigned IP addresses.
The ingress subdomain on which the assigned port is located, currently of the form ingres-.
The fully qualified domain can be formed by appending "proxylity.com" to the ingress domain, to do DNS lookups
for example.
The base64-encoded WireGuard public key for this listener. This attribute is only available for WireGuard listeners (when Protocols contains 'wg'). Use this key in client configurations to establish encrypted connections.
The PEM-encoded server certificate generated for a DTLS Listener. Use this attribute when distributing the Listener certificate through your deployment process or configuring client trust.