Key exchange
Purpose
It is generally difficult to share a symmetric key with another party because it needs to remain secret. Fortunately, a sender and recipient can exchange public keys, which do not need to be secret.
Both parties can then compute the same shared secret using their private key and the other party's public key. This shared secret can be turned into a symmetric key (e.g. for encryption).
For post-quantum security, a pre-shared key can also be shared between the two parties via a secure (e.g. encrypted) channel.
Private keys MUST NOT be shared. They MUST remain secret.
You often want to include ephemeral (one-time) key pairs in a key exchange as well. See the Notes for examples of how to do this.
Usage
GenerateKeyPair
Fills a span with a randomly generated private key and another span with the associated public key.
X25519.GenerateKeyPair(Span<byte> publicKey, Span<byte> privateKey)Exceptions
publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
Unable to generate key pair.
GenerateKeyPair
Fills a span with a private key generated using a random seed and another span with the associated public key.
Exceptions
publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
seed has a length not equal to SeedSize.
Unable to generate key pair from seed.
ComputePublicKey
Fills a span with the public key computed from a private key.
Exceptions
publicKey has a length not equal to PublicKeySize.
privateKey has a length not equal to PrivateKeySize.
Unable to compute public key from private key.
DeriveSenderSharedKey
Fills a span with the shared key for the sender using their private key, a recipient public key, and an optional pre-shared key.
Exceptions
sharedKey has a length not equal to SharedKeySize.
senderPrivateKey has a length not equal to PrivateKeySize.
recipientPublicKey has a length not equal to PublicKeySize.
If specified, preSharedKey has a length less than MinPreSharedKeySize or greater than MaxPreSharedKeySize.
Invalid recipient public key or unable to compute hash.
DeriveRecipientSharedKey
Fills a span with the shared key for the recipient using their private key, the sender's public key, and an optional pre-shared key.
Exceptions
sharedKey has a length not equal to SharedKeySize.
recipientPrivateKey has a length not equal to PrivateKeySize.
senderPublicKey has a length not equal to PublicKeySize.
If specified, preSharedKey has a length less than MinPreSharedKeySize or greater than MaxPreSharedKeySize.
Invalid sender public key or unable to compute hash.
ComputeSharedSecret
Fills a span with the unhashed X25519 shared secret for a given sender private key and recipient public key.
The number of possible keys is limited to the group size (~2^252), which is smaller than the key space.
Many (public key, private key) pairs produce the same shared secret. This can lead to vulnerabilities.
Therefore, it is important to pass the shared secret concatenated with the sender's public key and recipient's public key through a KDF.
Exceptions
sharedSecret has a length not equal to SharedSecretSize.
senderPrivateKey has a length not equal to PrivateKeySize.
recipientPublicKey has a length not equal to PublicKeySize.
Invalid public key.
Constants
These are used for validation and/or save you defining your own constants.
Notes
You generally want to use key exchange patterns from the Noise Protocol Framework or a protocol like Signal's X3DH. A rough summary of some popular Noise patterns can be found below.
You should derive different keys for each direction (sending/receiving) if using a counter nonce for encryption so you do not have to wait for an acknowledgment after every message. This can be done by deriving 512 bits of output keying material and using the first 256 bits for the sender and the latter 256 bits for the recipient.
X25519 public keys are distinguishable from random. This makes it very difficult to hide that cryptography is being used if that is a goal. Elligator can be used to do this, but it is not available in libsodium.
Do NOT use the same seed for X25519 and Ed25519 key generation. Instead, read the Ed25519 to X25519 page.
Non-Interactive Patterns
These are one-way patterns, so no back and forth between the sender and recipient is required. They are appropriate for offline applications (e.g. a file encryption program).
Authenticated Key Exchange
The recipient knows who sent the message, and only the recipient can decrypt the message. This can be achieved using the K pattern. The security properties are discussed here.
The sender generates an ephemeral key pair.
The sender computes an ephemeral shared secret using their ephemeral private key and the recipient's public key. The ephemeral private key is then erased from memory.
The sender also computes a long-term shared secret using their long-term private key and the recipient's public key.
The sender concatenates the ephemeral shared secret and long-term shared secret to form the input keying material for a KDF. The output keying material is used as the key to encrypt a message using an AEAD.
The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.
The recipient reads the ephemeral public key, computes the ephemeral shared secret using their private key and the sender's ephemeral public key, computes the long-term shared secret using their private key and the sender's long-term public key, derives the encryption key using the same KDF, and decrypts the ciphertext.
The X pattern can also be used, which is identical except that the sender's long-term public key is sent with the message under encryption instead of already being known to the recipient. The security properties are discussed here.
Deniable Authenticated Key Exchange
The recipient knows who sent the message, but both parties can decrypt the message. This means either party could have encrypted the message.
Noise does not provide a pattern for this, and it is weaker than non-deniable authenticated key exchange because a compromise of either party's private key is problematic.
Furthermore, the same shared secret will always be derived for the same (sender, recipient) pair, so you need to be even more careful about not reusing a nonce with the AEAD.
The sender computes a shared secret using their long-term private key and the recipient's public key.
The sender uses the shared secret as the input keying material for a KDF. The output keying material is used as the key to encrypt a message using an AEAD.
The recipient computes the shared secret using their private key and the sender's public key, derives the encryption key using the same KDF, and decrypts the ciphertext.
Anonymous Key Exchange
The recipient does not know who sent the message, and only the recipient can decrypt the message. This can be accomplished using the N pattern. The security properties are discussed here.
You generally want an authenticated key exchange because you often want to be sure that a message came from a certain person. Otherwise, an attacker can replace a message with one of their choosing, and the recipient will be none the wiser.
The sender generates an ephemeral key pair.
The sender computes the shared secret using their ephemeral private key and the recipient's public key. The ephemeral private key is then erased from memory.
The sender uses the shared secret as input keying material to a KDF. The output keying material is used as the key to encrypt a message using an AEAD.
The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.
The recipient reads the ephemeral public key, computes the shared secret using their private key and the sender's ephemeral public key, derives the encryption key using the same KDF, and decrypts the ciphertext.
Interactive Patterns
These are two-way patterns, so back and forth between the sender and recipient is required. They are appropriate for online applications and can provide better security properties than the one-way patterns.
Authenticated Key Exchange
The recipient knows who sent the message, and you eventually benefit from resistance to key compromise impersonation and strong forward secrecy. This can be achieved using the KK pattern.
The sender generates an ephemeral key pair.
The sender computes an ephemeral shared secret using their ephemeral private key and the recipient's long-term public key.
The sender also computes a long-term shared secret using their long-term private key and the recipient's long-term public key.
The sender concatenates the ephemeral shared secret and long-term shared secret to form the input keying material for a KDF. The output keying material is used as the key to encrypt a message using an AEAD.
The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.
The recipient reads the ephemeral public key, computes the ephemeral shared secret using their private key and the sender's ephemeral public key, computes the long-term shared secret using their private key and the sender's long-term public key, derives the encryption key using the same KDF, and decrypts the ciphertext.
The recipient generates an ephemeral key pair.
The recipient computes an ephemeral shared secret using their ephemeral private key and the sender's ephemeral public key.
The recipient computes another ephemeral shared secret using their ephemeral private key and the sender's long-term public key. The ephemeral private key is then erased from memory.
The recipient concatenates both ephemeral shared secrets to form the input keying material for a KDF. Importantly, the previous derived encryption key is included in this KDF usage (as a salt by the spec, but the info parameter could be used). The output keying material is used as the key to encrypt a message using an AEAD.
The recipient's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the sender.
The sender reads the ephemeral public key, computes the ephemeral shared secret using their ephemeral private key and the sender's ephemeral public key, erases their ephemeral private key, computes the other shared secret using their long-term private key and the recipient's ephemeral public key, and then derives the new encryption key in the same way the recipient did, which allows them to decrypt the ciphertext.
Subsequent messages can be encrypted using the same key and an incremented nonce.
Anonymous Key Exchange
The recipient does not know who sent the message. This can be accomplished using the NK pattern. The security properties are discussed here.
The sender generates an ephemeral key pair.
The sender computes the shared secret using their ephemeral private key and the recipient's public key.
The sender uses the shared secret as input keying material to a KDF. The output keying material is used as the key to encrypt a message using an AEAD.
The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.
The recipient reads the ephemeral public key, computes the shared secret using their private key and the sender's ephemeral public key, derives the encryption key using the same KDF, and decrypts the ciphertext.
The recipient generates an ephemeral key pair.
The recipient computes an ephemeral shared secret using their ephemeral private key and the sender's ephemeral public key. The ephemeral private key is then erased from memory.
The recipient uses the ephemeral shared secret as input keying material to a KDF. Importantly, the previous derived encryption key is included in this KDF usage (as a salt by the spec, but the info parameter could be used). The output keying material is used as the key to encrypt a message using an AEAD.
The recipient's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the sender.
The sender reads the ephemeral public key, computes the ephemeral shared secret using their ephemeral private key and the sender's ephemeral public key, erases their ephemeral private key, and then derives the new encryption key in the same way the recipient did, which allows them to decrypt the ciphertext.
Subsequent messages can be encrypted using the same key and an incremented nonce.
Last updated