Encryption

Note

This is part of the Low Level Transport for advanced users only.

When sending and receiving messages, attackers may be able to read them and extract information from them, if they are unencrypted. This is especially easy if you're on a wi-fi connection. If you're sending private data such as emails or passwords, you should always use encryption.

By default all connections are already encrypted, and you don't need to do anything extra to enable it.

Configure

To enable encryption all you have to do is make sure HostConfig.Encryption field is true before you create a host. By default this is enabled. Unencrypted connections can still be accepted even if encryption is enabled. When receiving incoming connections, make sure you check it is actually encrypted before accepting it.

// Create config with encryption enabled
HostConfig config = new HostConfig() {
	Encryption = true
};

// Create host
Host host = new Host(config, listener);

// ... create peers ...

How key exchange works

To encrypt and decrypt anything, peers first need to exchange encryption keys. If you simply send encryption keys normally, an attacker can read them and decrypt the packets themselves. To prevent this, we use what's called Diffie-Helmman key exchange to create encryption keys without actually sending them.

To create an encryption key, both peers first generate a random exchange key and a private key to go with it, then send the exchange key to eachother while keeping the private key a secret. After the exchange is done, both peers can then use their own private key and the received exchange key to generate a shared encryption key. Any attacker reading the packets is unable to generate the same encryption key without the private keys which are never sent, which means any encrypted communication from this point on is secure.

For the key exchange, netcode uses Curve25519 which offers 128-bits of security. For encryption, netcode uses AES with 256-bit keys.

Cryptanalysis attacks

Every time a packet is encrypted, a new initialization vector (16 bytes) is generated and added to the packet. This is to make sure a packet with the same data is never encrypted the same way so attackers cannot use cryptanalysis to retrieve encryption keys.

MITM attacks

If an attacker is able to not only read the packets, but also modify them, they can create their own fake key exchange between you and your destination. You then connect to the attacker, and attacker connects to your destination. This is called a Man-in-the-middle attack. To prevent it, you can use Authentication to make sure the peer that you're connecting to is actually who they say you are and not an attacker.

IP address Spoofing

Encryption can also protect you from IP address spoofing. Anybody can send an UDP packet from a fake IP address. This means someone could send a fake packet that is indistinguishable from a real packet. When you create encrypted connection, any spoofed packet will be dropped because it is not properly encrypted.