libsodium_crypto_kem (libsodium v3.0.1)

View Source

Post-quantum key encapsulation. This is the recommended default KEM; it currently uses X-Wing (libsodium_crypto_kem_xwing), a hybrid of ML-KEM-768 and X25519 that stays secure if either component is broken.

A recipient publishes a publickeybytes/0 byte public key PK. A sender calls enc/1 to obtain a ciphertextbytes/0 byte ciphertext CT and a sharedsecretbytes/0 byte shared secret SS, and sends CT to the recipient, who recovers the same SS with dec/2 and their secret key.

Seeds passed to seed_keypair/1 must be secret and uniformly random.

{PK, SK} = libsodium_crypto_kem:keypair(),
{CT, SS} = libsodium_crypto_kem:enc(PK),
SS = libsodium_crypto_kem:dec(CT, SK).

Summary

Types

ct()

A crypto_kem_CIPHERTEXTBYTES (1120-byte) binary.

pk()

A crypto_kem_PUBLICKEYBYTES (1216-byte) binary.

seed()

A crypto_kem_SEEDBYTES (32-byte) binary.

sk()

A crypto_kem_SECRETKEYBYTES (32-byte) binary.

ss()

A crypto_kem_SHAREDSECRETBYTES (32-byte) binary.

Functions

ciphertextbytes()

Return crypto_kem_ciphertextbytes(), in bytes.

dec(CT, SK)

Decapsulate the ciphertext CT with the secret key SK and return the shared secret SS.

enc(PK)

Encapsulate a fresh random shared secret to the public key PK. Returns {CT, SS}, where CT is sent to the holder of the secret key, or -1 when PK is invalid.

keypair()

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

primitive()

Return crypto_kem_primitive() as an atom.

publickeybytes()

Return crypto_kem_publickeybytes(), in bytes.

secretkeybytes()

Return crypto_kem_secretkeybytes(), in bytes.

seed_keypair(Seed)

Deterministically derive a key pair from the seedbytes/0 byte Seed, which must be secret and uniformly random. Returns {PK, SK}.

seedbytes()

Return crypto_kem_seedbytes(), in bytes.

sharedsecretbytes()

Return crypto_kem_sharedsecretbytes(), in bytes.

Types

ct()

-type ct() :: <<_:8960>>.

A crypto_kem_CIPHERTEXTBYTES (1120-byte) binary.

pk()

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

A crypto_kem_PUBLICKEYBYTES (1216-byte) binary.

seed()

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

A crypto_kem_SEEDBYTES (32-byte) binary.

sk()

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

A crypto_kem_SECRETKEYBYTES (32-byte) binary.

ss()

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

A crypto_kem_SHAREDSECRETBYTES (32-byte) binary.

Functions

ciphertextbytes()

-spec ciphertextbytes() -> Result when Result :: 1120.

Return crypto_kem_ciphertextbytes(), in bytes.

dec(CT, SK)

-spec dec(CT, SK) -> Result when CT :: ct(), SK :: sk(), Result :: ss() | -1.

Decapsulate the ciphertext CT with the secret key SK and return the shared secret SS.

A tampered or mismatched CT does not fail: implicit rejection returns a pseudorandom secret unrelated to the sender's, so the mismatch only surfaces when the secrets are used. Returns -1 only when the X25519 part of CT is a low-order point.

enc(PK)

-spec enc(PK) -> Result when PK :: pk(), Result :: {ct(), ss()} | -1.

Encapsulate a fresh random shared secret to the public key PK. Returns {CT, SS}, where CT is sent to the holder of the secret key, or -1 when PK is invalid.

keypair()

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

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

primitive()

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

Return crypto_kem_primitive() as an atom.

publickeybytes()

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

Return crypto_kem_publickeybytes(), in bytes.

secretkeybytes()

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

Return crypto_kem_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, which must be secret and uniformly random. Returns {PK, SK}.

seedbytes()

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

Return crypto_kem_seedbytes(), in bytes.

sharedsecretbytes()

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

Return crypto_kem_sharedsecretbytes(), in bytes.