How GamepadOS protects the link between your phone and PC: QR pairing and encryption

Your phone sends your controller state to your PC many times a second. That is a stream of small messages saying which buttons are down, where the sticks are and how far the triggers are pulled. On a home network nobody is listening, but on a shared one, in a dormitory, a hostel or an office, someone else could in theory watch those messages or send fake ones. This guide explains, without needing a maths background, how GamepadOS protects the link, and where the limits of that protection are.

The short version

• You pair once by scanning a QR code shown by the PC server. The code carries a secret that only your phone and your PC then know.
• Every time you connect, the two sides agree on brand-new encryption keys, and they only accept input from each other after both have proved they know the pairing secret.
• In current versions, every controller packet is encrypted and authenticated, and each one carries a counter, so a copied or altered packet is rejected.
• Nothing leaves your own network. This is about people on that network, not about the internet.

What travels between the phone and the PC

Only controller state: buttons, stick positions, trigger values, tilt and similar input, plus small acknowledgements and rumble going the other way. Your screen, your files and your account details are never part of this stream. Over Wi-Fi it travels as UDP on your local network, and over USB it travels through the cable. The privacy guide covers what stays local and what does not.

Step 1: pairing with the QR code

When you scan the QR code on the PC server, the phone learns three things: where your PC is on the network, which port to use, and a pairing secret. The secret is passed through the camera, from one screen to the other, and not through the air, so someone watching the network does not see it. This is the one-time step that makes your phone and your PC a matched pair.

Treat the QR code like a password. Do not post a screenshot of it, because the secret is inside it.

Step 2: fresh keys on every connection

Each time the phone connects, the two sides do a short exchange before any input is accepted:

1. Each side makes a brand-new temporary key pair and sends the public half to the other. Combining one side's private key with the other's public key gives both of them the same shared value, using a standard method called X25519. Someone who only watches cannot work that value out.
2. Both sides mix that shared value with the pairing secret and a summary of everything said so far, and from the result they derive the working keys, using a standard function called HKDF with SHA-256. There is one key for each direction.
3. Each side then sends a short confirmation that can only be produced by someone who knows the pairing secret. Both confirmations must check out before a single input packet is accepted.

Two things follow. A stranger who joins your Wi-Fi cannot complete this handshake, because they do not have the pairing secret and cannot produce the confirmation. And because the keys are new for every connection, recording a session today gives nobody the key to a session tomorrow.

Step 3: every packet is encrypted and checked

After the handshake, each controller message is sealed with AES-128-GCM, a widely used method that does two jobs at once: it scrambles the contents so they cannot be read, and it attaches a tag that lets the receiver detect any change. If even one bit was altered or the packet was made up, the tag does not match and the packet is dropped.

Each packet also carries a counter that only ever goes up. The receiver keeps track of the counters it has seen, so a packet that someone recorded and replays later is thrown away. The window is wide enough that the occasional reordered Wi-Fi packet is still fine. The order of the checks matters too: a forged packet is rejected before it can move the counter, so a flood of fake packets cannot knock your real input out.

The finished packet is small, a few dozen bytes, so protection does not make your input slower in any way you could feel. The sealing and opening take well under a millisecond, which is a rounding error next to the touchscreen sampling and the Wi-Fi itself. See where controller latency comes from for the real budget.

What the protected link is designed to stop

• Eavesdropping. Someone on the same Wi-Fi sees scrambled data, not your button presses.
• Fake input over the protected link. A device without the pairing secret cannot complete the handshake, so it cannot send input the PC will accept on that link.
• Replay. Recorded packets cannot be sent again to repeat your moves.
• Tampering. A modified packet fails its check and is ignored.

What it does not do

• Older versions. Versions of the app and the PC server from before this protection use an earlier format without encryption, and the PC server still understands that format so those versions keep working. To get the protected link, keep both the app and the PC server up to date.
• It is built for ordinary home, dorm and office networks. Like any pairing secret you scan or type, its strength depends on keeping it private, so it is protection against the other people on your network, not a promise that a determined attacker with unlimited time and a recording of your traffic could never succeed.
• It protects the link, not your PC. A game, a mod or a program you run yourself can still do whatever it likes with the input it receives.
• It does not hide that GamepadOS is running. Anyone on the network can see that two devices are talking, just not what they are saying.

Sensible habits

• Keep the QR code to yourself, and pair on a network you trust.
• On a network you do not trust at all, such as a public hotspot, prefer a USB connection. A cable has no one else on it. The USB guide shows how.
• Keep the PC server up to date, since updates are how fixes reach you.

If anything about this is unclear, or you spot something that looks wrong, please tell us through the contact form.