libsodium_crypto_kem_mlkem768 (libsodium v3.0.1)
View SourcePost-quantum key encapsulation with ML-KEM-768 (FIPS 203). Unless
interoperability requires plain ML-KEM, prefer libsodium_crypto_kem,
whose X-Wing default combines ML-KEM-768 with X25519.
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.
The seedbytes/0 byte key generation seed and the 32-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_mlkem768:keypair(),
{CT, SS} = libsodium_crypto_kem_mlkem768:enc(PK),
SS = libsodium_crypto_kem_mlkem768:dec(CT, SK).Summary
Types
A crypto_kem_mlkem768_CIPHERTEXTBYTES (1088-byte) binary.
A 32 (32-byte) binary.
A crypto_kem_mlkem768_PUBLICKEYBYTES (1184-byte) binary.
A crypto_kem_mlkem768_SEEDBYTES (64-byte) binary.
A crypto_kem_mlkem768_SECRETKEYBYTES (2400-byte) binary.
A crypto_kem_mlkem768_SHAREDSECRETBYTES (32-byte) binary.
Functions
Return crypto_kem_mlkem768_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 not a valid encoding.
Encapsulate to the public key PK using the 32-byte Seed (the
FIPS 203 message m) instead of fresh randomness. Seed must be
secret, uniformly random, and never reused. Returns {CT, SS}, or -1
when PK is not a valid encoding.
Generate a random key pair. Returns {PK, SK}.
Return crypto_kem_mlkem768_publickeybytes(), in bytes.
Return crypto_kem_mlkem768_secretkeybytes(), in bytes.
Deterministically derive a key pair from the seedbytes/0 byte Seed
(the FIPS 203 d || z), which must be secret and uniformly random.
Returns {PK, SK}.
Return crypto_kem_mlkem768_seedbytes(), in bytes.
Return crypto_kem_mlkem768_sharedsecretbytes(), in bytes.
Types
-type ct() :: <<_:8704>>.
A crypto_kem_mlkem768_CIPHERTEXTBYTES (1088-byte) binary.
-type enc_seed() :: <<_:256>>.
A 32 (32-byte) binary.
-type pk() :: <<_:9472>>.
A crypto_kem_mlkem768_PUBLICKEYBYTES (1184-byte) binary.
-type seed() :: <<_:512>>.
A crypto_kem_mlkem768_SEEDBYTES (64-byte) binary.
-type sk() :: <<_:19200>>.
A crypto_kem_mlkem768_SECRETKEYBYTES (2400-byte) binary.
-type ss() :: <<_:256>>.
A crypto_kem_mlkem768_SHAREDSECRETBYTES (32-byte) binary.
Functions
-spec ciphertextbytes() -> Result when Result :: 1088.
Return crypto_kem_mlkem768_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.
Encapsulate a fresh random shared secret to the public key PK.
Returns {CT, SS}, or -1 when PK is not a valid encoding.
-spec enc_deterministic(PK, Seed) -> Result when PK :: pk(), Seed :: enc_seed(), Result :: {ct(), ss()} | -1.
Encapsulate to the public key PK using the 32-byte Seed (the
FIPS 203 message m) instead of fresh randomness. Seed must be
secret, uniformly random, and never reused. Returns {CT, SS}, or -1
when PK is not a valid encoding.
Generate a random key pair. Returns {PK, SK}.
-spec publickeybytes() -> Result when Result :: 1184.
Return crypto_kem_mlkem768_publickeybytes(), in bytes.
-spec secretkeybytes() -> Result when Result :: 2400.
Return crypto_kem_mlkem768_secretkeybytes(), in bytes.
Deterministically derive a key pair from the seedbytes/0 byte Seed
(the FIPS 203 d || z), which must be secret and uniformly random.
Returns {PK, SK}.
-spec seedbytes() -> Result when Result :: 64.
Return crypto_kem_mlkem768_seedbytes(), in bytes.