Crypto handshake human doc

[kurnevsky]

Crypto connection can have one of the next statuses:

• CookieRequesting
• HandshakeSending
• NotConfirmed
• Established

Usually the initial status is CookieRequesting. But it also can be NotConfirmed in case if we received a CryptoHandshake packet before the connection was initialized.

CookieRequesting

In this status we send up to 8 CookieRequest packets every second and wait for a CookieResponse packet.

Cookie is an encrypted with private symmetric key pair of keys: DHT public key and long term public key. Also it contains a timestamp so that it can be valid only for 8 seconds after creation.

When we receive a CookieResponse packet we check that the ID of this packet is equal to the ID from the request and if so we change the status to HandshakeSending.

If we received a CryptoHandshake packet earlier than a CookieResponse packet we take the Cookie from received CryptoHandshake packet and change the status to HandshakeSending as well.

If we didn't get neither CookieResponse nor CryptoHandshake packets we consider the connection as timed out.

HandshakeSending

In this status we send up to 8 CryptoHandshake packets every second and wait for CryptoHandshake packet from the other side.

When we receive a CryptoHandshake packet we check the Cookie from this packet. First of all it should have the same hash as enclosed in encrypted payload. With this check we ensure that the Cookie wasn't changed or modified which is possible because it lies outside of encrypted payload. Then if we can decrypt this Cookie with our private symmetric key we check its content. The Cookie shouldn't be timed out and both DHT and long term public keys should match connection keys. If only long term key is correct but DHT key is different we assume that DHT key was changed and send the appropriate message.

If after all the Cookie is considered correct we change the status to NotConfirmed.

NotConfirmed

In this status we continue sending CryptoHandshake packets because we don't know if the other side received our CryptoHandshake packet.

When we receive the first valid CryptoData packet we change the status to Established.

Established

In this status the connection considered as fully established.

[kpp]

Move this chapter to https://github.com/tox-rs/book