Encryption methods as implemented in data_encrypt require that parties have a
shared secret key. But often we wish to establish a secure channel with a party we have
no prior relationship with. Diffie-hellman is a method for jointly agreeing on a shared
secret without ever exchanging the secret itself. Sodium implements
Curve25519, a state-of-the-art Diffie-Hellman
function suitable for a wide variety of applications.
The method conists of two steps (see examples). First, both parties generate a random private
key and derive the corresponding public key using pubkey. These public keys are not
confidential and can be exchanged over an insecure channel. After the public keys are exchanged,
both parties will be able to calculate the (same) shared secret by combining his/her own private
key with the other person's public key using diffie_hellman.
After the shared secret has been established, the private and public keys are disposed,
and parties can start encrypting communications based on the shared secret using e.g.
data_encrypt. Because the shared secret cannot be calculated using only the public
keys, the process is safe from eavesdroppers.