libsodium_crypto_kx (libsodium v3.0.1)

Key exchange based on X25519 and BLAKE2b.

A client and a server each hold a key pair of publickeybytes/0 and secretkeybytes/0 bytes. After exchanging public keys, both sides derive the same pair of sessionkeybytes/0 byte session keys: a key for receiving (Rx) and a key for transmitting (Tx). The client's Tx equals the server's Rx and vice versa.

The session keys are bound to both public keys; use them with a symmetric construction such as libsodium_crypto_secretbox.

{ClientPK, ClientSK} = libsodium_crypto_kx:keypair(),
{ServerPK, ServerSK} = libsodium_crypto_kx:keypair(),
{ClientRx, ClientTx} = libsodium_crypto_kx:client_session_keys(ClientPK, ClientSK, ServerPK),
{ServerRx, ServerTx} = libsodium_crypto_kx:server_session_keys(ServerPK, ServerSK, ClientPK),
ClientRx = ServerTx,
ClientTx = ServerRx.

Summary

Types

client_pk()

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

client_sk()

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

pk()

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

rx()

A crypto_kx_SESSIONKEYBYTES (32-byte) binary.

seed()

A crypto_kx_SEEDBYTES (32-byte) binary.

server_pk()

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

server_sk()

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

sk()

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

tx()

A crypto_kx_SESSIONKEYBYTES (32-byte) binary.

Functions

client_session_keys(ClientPK, ClientSK, ServerPK)

Compute the client's session keys from its key pair ClientPK and ClientSK and the server's public key ServerPK.

keypair()

Generate a random key pair. Returns {PK, SK}.

primitive()

Return crypto_kx_primitive() as an atom.

publickeybytes()

Return crypto_kx_publickeybytes(), in bytes.

secretkeybytes()

Return crypto_kx_secretkeybytes(), in bytes.

seed_keypair(Seed)

Deterministically derive a key pair from the seedbytes/0 byte Seed. Returns {PK, SK}.

seedbytes()

Return crypto_kx_seedbytes(), in bytes.

server_session_keys(ServerPK, ServerSK, ClientPK)

Compute the server's session keys from its key pair ServerPK and ServerSK and the client's public key ClientPK.

sessionkeybytes()

Return crypto_kx_sessionkeybytes(), in bytes.

Types

client_pk()

-type client_pk() :: <<_:256>>.

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

client_sk()

-type client_sk() :: <<_:256>>.

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

pk()

-type pk() :: <<_:256>>.

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

rx()

-type rx() :: <<_:256>>.

A crypto_kx_SESSIONKEYBYTES (32-byte) binary.

seed()

-type seed() :: <<_:256>>.

A crypto_kx_SEEDBYTES (32-byte) binary.

server_pk()

-type server_pk() :: <<_:256>>.

A crypto_kx_PUBLICKEYBYTES (32-byte) binary.

server_sk()

-type server_sk() :: <<_:256>>.

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

sk()

-type sk() :: <<_:256>>.

A crypto_kx_SECRETKEYBYTES (32-byte) binary.

tx()

-type tx() :: <<_:256>>.

A crypto_kx_SESSIONKEYBYTES (32-byte) binary.

Functions

client_session_keys(ClientPK, ClientSK, ServerPK)

-spec client_session_keys(ClientPK, ClientSK, ServerPK) -> Result
                             when
                                 ClientPK :: client_pk(),
                                 ClientSK :: client_sk(),
                                 ServerPK :: server_pk(),
                                 Result :: {rx(), tx()} | -1.

Compute the client's session keys from its key pair ClientPK and ClientSK and the server's public key ServerPK.

Returns {Rx, Tx}, or -1 when ServerPK is unacceptable.

keypair()

-spec keypair() -> Result when Result :: {pk(), sk()} | -1.

Generate a random key pair. Returns {PK, SK}.

primitive()

-spec primitive() -> Result when Result :: x25519blake2b.

Return crypto_kx_primitive() as an atom.

publickeybytes()

-spec publickeybytes() -> Result when Result :: 32.

Return crypto_kx_publickeybytes(), in bytes.

secretkeybytes()

-spec secretkeybytes() -> Result when Result :: 32.

Return crypto_kx_secretkeybytes(), in bytes.

seed_keypair(Seed)

-spec seed_keypair(Seed) -> Result when Seed :: seed(), Result :: {pk(), sk()} | -1.

Deterministically derive a key pair from the seedbytes/0 byte Seed. Returns {PK, SK}.

seedbytes()

-spec seedbytes() -> Result when Result :: 32.

Return crypto_kx_seedbytes(), in bytes.

server_session_keys(ServerPK, ServerSK, ClientPK)

-spec server_session_keys(ServerPK, ServerSK, ClientPK) -> Result
                             when
                                 ServerPK :: server_pk(),
                                 ServerSK :: server_sk(),
                                 ClientPK :: client_pk(),
                                 Result :: {rx(), tx()} | -1.

Compute the server's session keys from its key pair ServerPK and ServerSK and the client's public key ClientPK.

Returns {Rx, Tx}, or -1 when ClientPK is unacceptable.

sessionkeybytes()

-spec sessionkeybytes() -> Result when Result :: 32.

Return crypto_kx_sessionkeybytes(), in bytes.