SDK Shield

Games and apps embed an SDK whose first packet carries an app token; nodes check it at L4 with replay protection. DDoS and CC protection, origin hiding.

What it solves

Game and app logins, matches and voice run over long-lived layer-4 connections. Once attackers know a node address they can run CC attacks with connections that look legitimate, and the node cannot tell real players from scripts. SDK Shield lets a client prove it belongs to your app: the client embeds the SDK, which fetches a signed list of protection nodes from the control plane, picks a node by latency and connects with an app token in the first packet. Nodes check the token and replay protection; valid connections go to the origin as usual, invalid ones are closed, and a source that keeps failing is blocked in the kernel.

• DDoS and CC protection: large traffic without a valid token (floods, scans, generic CC scripts) is dropped at the node on the first packet.
• Origin hiding: clients only get protection node addresses and ports; the node list contains no origin address.
• When a node fails, the SDK moves to the next one at once instead of waiting for DNS changes and TTL expiry.

Turning it on

SDK Shield is an official module of the commercial edition, free for now and claimed per installation in the plugin store. The community edition does not include it.

1. An administrator buys SDK Shield in the plugin store. The menu Layer 4 forwarding → SDK Shield appears.
2. If the control plane was installed before a version with SDK Shield (it was upgraded), run the key setup once as root on the control plane host. Until then, creating apps and generating keys reports that SDK Shield keys are not configured. A freshly installed control plane does not need this step.

curl --proto '=https' -fsSL -o install-control.sh https://auth.cdnca.com/downloads/install-control.sh
bash install-control.sh converge-sdkshield apply
bash install-control.sh converge-sdkshield checkCopy

The command generates the key on the host (it is not printed), restarts the control plane service and waits until it is ready; if it does not become ready, the previous state is restored. It can be run again; when keys are already configured it changes nothing. check prints installer or converged when keys are configured.

3. Create an SDK app and save the AppSecret (shown once).
4. On the app's L4 forwards tab, bind the TCP / UDP forwards your game uses. Saving republishes them; nodes must run a version that supports SDK Shield, otherwise publishing is refused and the nodes are listed.
5. Download the SDK on the Integration tab (released with each control plane version, available after sign-in, with a SHA-256 to verify) and integrate it: initialise it with the AppID, key number, AppSecret, node list URL and the built-in list signing public key, and switch your code to the SDK's dial functions.
6. To offer it to tenants, turn on SDK Shield in a package's resource limits and set SDK apps (-1 for unlimited).

Main settings

SDKs are available for Go, Java (Android), Swift (iOS / macOS), C (for Unity, Unreal and native Windows plugins) and a Unity C# wrapper.

Typical uses

• A mobile game logs in over TCP and plays matches over UDP: bind both forwards to one app and initialise the SDK once.
• Mirror the node list to your own HTTPS server or object storage so players never see the control plane address. The mirror must send a correct HTTP Date header, which the SDK uses to correct the player's clock.
• An AppSecret is extracted from the client: generate a new key, ship a new client, and revoke the old key once its handshakes over the last 24 hours reach 0. Give each distribution channel its own key number so a leak only revokes one channel.

Limits and notes

• It only does DDoS and CC protection and origin hiding. It does not encrypt traffic (use TLS or your own encryption end to end; nodes pass it through), does not parse application protocols, and the node list only contains the fixed nodes the administrator assigned.
• Performance: listeners without SDK mode, HTTP sites and plain L4 forwards are unchanged, and their node configuration is byte-for-byte the same. SDK TCP adds one check on the first packet of a connection and then forwards as usual, with no per-packet work. Long SDK UDP sessions cost about 1.4–1.5 times as much per packet as without SDK (measured).
• Forwards you can bind: a dedicated, single port (not a range), no inbound PROXY protocol and no TLS passthrough.
• UDP cannot pass the real client IP to the origin; report it in your own protocol or use a TCP connection of the same app. A UDP origin should drop 64-byte handshake datagrams that start with C5 D7 01 01 (the SDK has a helper for this).
• The AppSecret is built into the client and can eventually be extracted. An attacker with the key can forge tokens, but each token works once and for one node only, and the handshake rate limit, per-IP connection rate and L4 protection rules still apply.
• After the licence expires or is revoked, or the module is disabled on this control plane: published SDK listeners keep checking tokens and players stay connected, but apps, keys and bindings cannot be created or changed, the node list URL returns 404 and the SDK keeps its cached list.
• How far each SDK is verified: Go is tested end to end against real nodes; Java has not run on an Android device or emulator; Swift unit tests ran in the iOS simulator; the C library is tested on macOS and Linux, cross-compiled only for Windows, and not built for Android or iOS; the Unity wrapper has not run inside the engine.