Key exchange

Key exchange

Using the key exchange API, two parties can securely compute a set of ephemeral, shared secret keys, that can be used to securely exchange messages.

The general pattern to build a secure channel is:

• Pick the variant that fits your application needs
• Use the hydro_kx_ functions from that variant to build and parse packets to be exchanged between parties
• Eventually, both parties will compute a shared secret, that can be used with hydro_secretbox().

Libhydrogen implements three variants based on the NOISE framework:

The N key exchange variant

• What the client needs to know about the server: the server's public key
• What the server needs to know about the client: nothing

This variant is designed to anonymously send messages to a recipient using its public key.

N variant API documentation

The KK key exchange variant

• What the client needs to know about the server: the server's public key
• What the server needs to know about the client: the client's public key

This variant is designed to exchange messages between two parties that already know each other's public key.

KK variant API documentation

The XX key exchange variant

• What the client needs to know about the server: nothing
• What the server needs to know about the client: nothing

This is the most versatile variant, but it requires two round trips.

In this variant, the client and the server don't need to share any prior data.

However, the peers public keys will be exchanged. Discovered public keys can then be discarded, used for authentication, or reused later with the KK variant.

XX variant API documentation

Common constants

#define hydro_kx_SESSIONKEYBYTES 32
#define hydro_kx_PUBLICKEYBYTES 32
#define hydro_kx_SECRETKEYBYTES 32
#define hydro_kx_PSKBYTES 32

Common data types

typedef struct hydro_kx_keypair {
    uint8_t pk[hydro_kx_PUBLICKEYBYTES];
    uint8_t sk[hydro_kx_SECRETKEYBYTES];
} hydro_kx_keypair;

typedef struct hydro_kx_session_keypair {
    uint8_t rx[hydro_kx_SESSIONKEYBYTES];
    uint8_t tx[hydro_kx_SESSIONKEYBYTES];
} hydro_kx_session_keypair;

typedef struct hydro_kx_state {
  ...
} hydro_kx_state;

Pre-shared keys

These key exchange mechanisms support optional pre-shared secret keys.

In order to do so, the psk parameter present in the above APIs can be either set to NULL, or to hydro_kx_PSKBYTES secret bytes.

If psk is not NULL, the same value has to be used with all functions involved in the key exchange, and has to be the same on the client and on the server.

In variants accepting anonymous clients, the PSK can be useful to restrict access to a set of clients knowing this extra key.

In variants requiring more than a single round-trip, the PSK can be useful to avoid extra round trips on unsuccessful authentication attempts.

Algorithm

These protocols use constructions from the NOISE framework, with the Gimli construction used for hashing and encryption.

The AEAD construction is similar to the NORX v3.0 AEAD construction, with the following differences:

• The header includes all the metadata, including the nonce
• Gimli is the permutation function