libsodium_crypto_kem_xwing (libsodium v3.0.1)
View SourcePost-quantum hybrid key encapsulation with X-Wing, which combines
ML-KEM-768 and X25519 so that the shared secret stays secure as long as
either component does. It is the primitive behind libsodium_crypto_kem,
the recommended default.
enc/1 encapsulates a sharedsecretbytes/0 byte shared secret SS to a
publickeybytes/0 byte public key PK, producing a ciphertextbytes/0
byte ciphertext CT; dec/2 recovers SS from CT with the
secretkeybytes/0 byte secret key SK, which is itself the key
generation seed.
The seedbytes/0 byte key generation seed and the 64-byte encapsulation
seed of enc_deterministic/2 must be secret and uniformly random; they
exist for known-answer tests and deterministic derivation.
{PK, SK} = libsodium_crypto_kem_xwing:keypair(),
{CT, SS} = libsodium_crypto_kem_xwing:enc(PK),
SS = libsodium_crypto_kem_xwing:dec(CT, SK).Summary
Types
A crypto_kem_xwing_CIPHERTEXTBYTES (1120-byte) binary.
A 64 (64-byte) binary.
A crypto_kem_xwing_PUBLICKEYBYTES (1216-byte) binary.
A crypto_kem_xwing_SEEDBYTES (32-byte) binary.
A crypto_kem_xwing_SECRETKEYBYTES (32-byte) binary.
A crypto_kem_xwing_SHAREDSECRETBYTES (32-byte) binary.
Functions
Return crypto_kem_xwing_ciphertextbytes(), in bytes.
Decapsulate the ciphertext CT with the secret key SK and return the
shared secret SS.
Encapsulate a fresh random shared secret to the public key PK.
Returns {CT, SS}, or -1 when PK is invalid.
Encapsulate to the public key PK using the 64-byte Seed (the
ML-KEM-768 encapsulation seed followed by the ephemeral X25519 secret
key) instead of fresh randomness. Seed must be secret, uniformly
random, and never reused. Returns {CT, SS}, or -1 when PK is
invalid.
Generate a random key pair. Returns {PK, SK}.
Return crypto_kem_xwing_publickeybytes(), in bytes.
Return crypto_kem_xwing_secretkeybytes(), in bytes.
Deterministically derive a key pair from the seedbytes/0 byte Seed,
which must be secret and uniformly random. Returns {PK, SK}.
Return crypto_kem_xwing_seedbytes(), in bytes.
Return crypto_kem_xwing_sharedsecretbytes(), in bytes.
Types
-type ct() :: <<_:8960>>.
A crypto_kem_xwing_CIPHERTEXTBYTES (1120-byte) binary.
-type enc_seed() :: <<_:512>>.
A 64 (64-byte) binary.
-type pk() :: <<_:9728>>.
A crypto_kem_xwing_PUBLICKEYBYTES (1216-byte) binary.
-type seed() :: <<_:256>>.
A crypto_kem_xwing_SEEDBYTES (32-byte) binary.
-type sk() :: <<_:256>>.
A crypto_kem_xwing_SECRETKEYBYTES (32-byte) binary.
-type ss() :: <<_:256>>.
A crypto_kem_xwing_SHAREDSECRETBYTES (32-byte) binary.
Functions
-spec ciphertextbytes() -> Result when Result :: 1120.
Return crypto_kem_xwing_ciphertextbytes(), in bytes.
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.
Encapsulate a fresh random shared secret to the public key PK.
Returns {CT, SS}, or -1 when PK is invalid.
-spec enc_deterministic(PK, Seed) -> Result when PK :: pk(), Seed :: enc_seed(), Result :: {ct(), ss()} | -1.
Encapsulate to the public key PK using the 64-byte Seed (the
ML-KEM-768 encapsulation seed followed by the ephemeral X25519 secret
key) instead of fresh randomness. Seed must be secret, uniformly
random, and never reused. Returns {CT, SS}, or -1 when PK is
invalid.
Generate a random key pair. Returns {PK, SK}.
-spec publickeybytes() -> Result when Result :: 1216.
Return crypto_kem_xwing_publickeybytes(), in bytes.
-spec secretkeybytes() -> Result when Result :: 32.
Return crypto_kem_xwing_secretkeybytes(), in bytes.
Deterministically derive a key pair from the seedbytes/0 byte Seed,
which must be secret and uniformly random. Returns {PK, SK}.
-spec seedbytes() -> Result when Result :: 32.
Return crypto_kem_xwing_seedbytes(), in bytes.