7.1 How invitations work

When an invitation is created on a node (which from now on we will call the server) using the tinc invite command, an invitation file is created that contains all the information necessary for the invitee (which we will call the client) to create its configuration files. The invitation file is stays on the server, but a URL is generated that has enough information for the client to contact the server and to retrieve the invitation file. The whole URL is around 80 characters long and looks like this:

server.example.org:12345/cW1NhLHS-1WPFlcFio8ztYHvewTTKYZp8BjEKg3vbMtDz7w4

It is composed of four parts:

hostname : port / keyhash cookie

The hostname and port tell the client how to reach the tinc daemon on the server. The part after the slash looks like one blob, but is composed of two parts. The keyhash is the hash of the public key of the server. The cookie is a shared secret that identifies the client to the server.

When the client connects to the server in order to join the VPN, the client and server will exchange temporary public keys. The client verifies that the hash of the server’s public key matches the keyhash from the invitation URL. If not, it will immediately exit with an error. Otherwise, an ECDH exchange will happen so the client and server can communicate privately with each other. The client will then present the cookie to the server. The server uses this to look up the corresponding invitation file it generated earlier. If it exists, it will send the invitation file to the client. The client will also create a permanent public key, and send it to the server. After the exchange is completed, the connection is broken. The server creates a host config file for the client containing the client’s permanent public key, and the client creates tinc.conf, host config files and possibly a tinc-up script based on the information in the invitation file.

It is important that the invitation URL is kept secret until it is used; if another person gets a copy of the invitation URL before the real client runs the tinc join command, then that other person can try to join the VPN.