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

ArgumentOutOfRangeException

publicKey has a length not equal to PublicKeySize.

ArgumentOutOfRangeException

privateKey has a length not equal to PrivateKeySize.

CryptographicException

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.

X25519.GenerateKeyPair(Span<byte> publicKey, Span<byte> privateKey, ReadOnlySpan<byte> seed)

Exceptions

ArgumentOutOfRangeException

publicKey has a length not equal to PublicKeySize.

ArgumentOutOfRangeException

privateKey has a length not equal to PrivateKeySize.

ArgumentOutOfRangeException

seed has a length not equal to SeedSize.

CryptographicException

Unable to generate key pair from seed.

ComputePublicKey

Fills a span with the public key computed from a private key.

X25519.ComputePublicKey(Span<byte> publicKey, ReadOnlySpan<byte> privateKey)

Exceptions

ArgumentOutOfRangeException

publicKey has a length not equal to PublicKeySize.

ArgumentOutOfRangeException

privateKey has a length not equal to PrivateKeySize.

CryptographicException

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.

X25519.DeriveSenderSharedKey(Span<byte> sharedKey, ReadOnlySpan<byte> senderPrivateKey, ReadOnlySpan<byte> recipientPublicKey, ReadOnlySpan<byte> preSharedKey = default)

Exceptions

ArgumentOutOfRangeException

sharedKey has a length not equal to SharedKeySize.

ArgumentOutOfRangeException

senderPrivateKey has a length not equal to PrivateKeySize.

ArgumentOutOfRangeException

recipientPublicKey has a length not equal to PublicKeySize.

ArgumentOutOfRangeException

If specified, preSharedKey has a length less than MinPreSharedKeySize or greater than MaxPreSharedKeySize.

CryptographicException

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.

X25519.DeriveRecipientSharedKey(Span<byte> sharedKey, ReadOnlySpan<byte> recipientPrivateKey, ReadOnlySpan<byte> senderPublicKey, ReadOnlySpan<byte> preSharedKey = default)

Exceptions

ArgumentOutOfRangeException

sharedKey has a length not equal to SharedKeySize.

ArgumentOutOfRangeException

recipientPrivateKey has a length not equal to PrivateKeySize.

ArgumentOutOfRangeException

senderPublicKey has a length not equal to PublicKeySize.

ArgumentOutOfRangeException

If specified, preSharedKey has a length less than MinPreSharedKeySize or greater than MaxPreSharedKeySize.

CryptographicException

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.

X25519.ComputeSharedSecret(Span<byte> sharedSecret, ReadOnlySpan<byte> senderPrivateKey, ReadOnlySpan<byte> recipientPublicKey)

1. The number of possible keys is limited to the group size (~2^252), which is smaller than the key space.

2. 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

ArgumentOutOfRangeException

sharedSecret has a length not equal to SharedSecretSize.

ArgumentOutOfRangeException

senderPrivateKey has a length not equal to PrivateKeySize.

ArgumentOutOfRangeException

recipientPublicKey has a length not equal to PublicKeySize.

CryptographicException

Invalid public key.

Constants

These are used for validation and/or save you defining your own constants.

public const int PublicKeySize = 32;
public const int PrivateKeySize = 32;
public const int SeedSize = 32;
public const int SharedSecretSize = 32;
public const int SharedKeySize = 32;
public const int PreSharedKeySize = 32;
public const int MinPreSharedKeySize = 16;
public const int MaxPreSharedKeySize = 64;

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.

1. The sender generates an ephemeral key pair.

2. 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.

3. The sender also computes a long-term shared secret using their long-term private key and the recipient's public key.

4. 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.

5. The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.

6. 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.

1. The sender computes a shared secret using their long-term private key and the recipient's public key.

2. 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.

3. 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.

1. The sender generates an ephemeral key pair.

2. 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.

3. 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.

4. The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.

5. 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.

1. The sender generates an ephemeral key pair.

2. The sender computes an ephemeral shared secret using their ephemeral private key and the recipient's long-term public key.

3. The sender also computes a long-term shared secret using their long-term private key and the recipient's long-term public key.

4. 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.

5. The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.

6. 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.

7. The recipient generates an ephemeral key pair.

8. The recipient computes an ephemeral shared secret using their ephemeral private key and the sender's ephemeral public key.

9. 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.

10. 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.

11. The recipient's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the sender.

12. 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.

13. 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.

1. The sender generates an ephemeral key pair.

2. The sender computes the shared secret using their ephemeral private key and the recipient's public key.

3. 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.

4. The sender's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the recipient.

5. 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.

6. The recipient generates an ephemeral key pair.

7. 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.

8. 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.

9. The recipient's ephemeral public key is prepended to the ciphertext, and the ciphertext is sent to the sender.

10. 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.

11. Subsequent messages can be encrypted using the same key and an incremented nonce.