NAME
Crypt::Sodium::XS::kem - Key encapsulation
SYNOPSIS
use Crypt::Sodium::XS;
use Crypt::Sodium::XS::kem;
die "no kem support" unless Crypt::Sodium::XS::kem->available;
my $kem = Crypt::Sodium::XS->kem;
# server:
my ($pk, $sk) = $kem->keypair;
# $pk is made available to client in trustworthy manner
# client:
my ($ct, $client_ss) = $kem->enc($pk);
# $ct is transferred to server
# server:
my $server_ss = $kem->dec($ct, $sk);
# both sides have shared secret
print "secrets match!\n" if $client_ss->compare($server_ss) == 0;DESCRIPTION
A key encapsulation mechanism creates a shared secret for a recipient using the public key of that recipient.
The sender obtains the shared secret directly during encapsulation. The recipient obtains the same shared secret by decapsulating the ciphertext with the secret key.
This is useful for bootstrapping session keys or building hybrid encryption schemes.
Unlike traditional Diffie-Hellman style key exchange, encapsulation is asymmetric: only the recipient needs a long-term key pair, and the sender does not need to publish a public key in order to create a shared secret.
If the application needs sender authentication in addition to confidentiality, combine key encapsulation with a signature scheme or an authenticated key exchange.
CONSTRUCTOR
The constructor is called with the Crypt::Sodium::XS->kem method.
my $kem = Crypt::Sodium::XS->kem;
my $kem = Crypt::Sodium::XS->kem(primitive => 'mlkem768');Returns a new kem object.
Implementation detail: the returned object is blessed into Crypt::Sodium::XS::OO::kem.
ATTRIBUTES
primitive
my $primitive = $kem->primitive;
$kem->primitive('mlkem768');Gets or sets the primitive used for all operations by this object. It must be one of the primitives listed in "PRIMITIVES", including default.
METHODS
available
my $has_kem = $kem->available;
my $has_kem = Crypt::Sodium::XS::kem->available;Returns true if Crypt::Sodium::XS supports KEM, false otherwise. KEM will only be supported if Crypt::Sodium::XS was built with a new enough version of libsodium (at least 1.0.22).
Can be called as a class method.
primitives
my @primitives = $kem->primitives;
my @primitives = Crypt::Sodium::XS::kem->primitives;Returns a list of all supported primitive names, including default.
Can be called as a class method.
PRIMITIVE
my $primitive = $kem->PRIMITIVE;Returns the primitive used for all operations by this object. Note this will never be default but would instead be the primitive it represents.
dec
my $shared_secret = $kem->dec($ciphertext, $secret_key, $flags);$ciphertxt is the encrypted ciphertext received from the sender. It must be "CIPHERTEXTBYTES" bytes.
$secret_key is the secret key used to decrypt the ciphertext. It must be "SECRETKEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.
$flags is optional. It is the flags used for the $shared_secret Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.
Returns a Crypt::Sodium::XS::MemVault: the shared secret of "SHAREDSECRETBYTES" bytes.
TODO
enc
my ($ciphertext, $shared_secret) = $kem->enc($public_key, $flags);$public_key is the receiver's public key to which $ciphertext is encrypted.
$flags is optional. It is the flags used for the $shared_secret Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.
Returns the encrypted ciphertext of "CIPHERTEXTBYTES" bytes and a Crypt::Sodium::XS::MemVault: the shared secret of "SHAREDSECRETBYTES" bytes.
keypair
my ($public_key, $secret_key) = $kem->keypair($seed, $flags);$seed is optional. It must be "SEEDBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault. Using the same seed will generate the same key pair, so it must be kept confidential. If omitted, a key pair is randomly generated.
$flags is optional. It is the flags used for the $secret_key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.
Returns a public key of "PUBLICKEYBYTES" bytes and a Crypt::Sodium::XS::MemVault: the secret key of "SECRETKEYBYTES" bytes.
CIPHERTEXTBYTES
Returns the size, in bytes, of ciphertext produced by "enc".
PUBLICKEYBYTES
Returns the size, in bytes, of a public key.
SECRETKEYBYTES
Returns the size, in bytes, of a private key.
SHAREDSECRETBYTES
Returns the size, in bytes, of a shared secret.
SEEDBYTES
Returns the size, in bytes, of a seed used by "keypair".
PRIMITIVES
mlkem768
xwing (default)
X-Wing combines ML-KEM768 with X25519 in order to provide protection against both classical and quantum adversaries.
FUNCTIONS
The object API above is the recommended way to use this module. The functions and constants documented below can be imported instead or in addition.
Nothing is exported by default. A :default tag imports the functions and constants documented below. A separate :<primitive> import tag is provided for each of the primitives listed in "PRIMITIVES". These tags import the kem_<primitive>_* functions and constants for that primitive. A :all tag imports everything.
kem_dec
kem_<primitive>_dec
my $shared_secret = kem_dec($ciphertext, $secret_key);Same as "dec".
kem_enc
kem_<primitive>_enc
my ($ciphertext, $shared_secret) = kem_enc($public_key);Same as "enc".
kem_keypair
kem_<primitive>_keypair
my ($public_key, $secret_key) = kem_keypair;CONSTANTS
Same as "keypair".
kem_CIPHERTEXTBYTES
kem_<primitive>_CIPHERTEXTBYTES
Same as "CIPHERTEXTBYTES".
kem_PUBLICKEYBYTES
kem_<primitive>_PUBLICKEYBYTES
Same as "PUBLICKEYBYTES".
kem_SECRETKEYBYTES
kem_<primitive>_SECRETKEYBYTES
Same as "SECRETKEYBYTES".
kem_SHAREDSECRETBYTES
kem_<primitive>_SHAREDSECRETBYTES
Same as "SHAREDSECRETBYTES".
kem_SEEDBYTES
kem_<primitive>_SEEDBYTES
Same as "SEEDBYTES".
SEE ALSO
FEEDBACK
For reporting bugs, giving feedback, submitting patches, etc. please use the following:
RT queue at https://rt.cpan.org/Dist/Display.html?Name=Crypt-Sodium-XS
IRC channel
#sodiumonirc.perl.org.Email the author directly.
AUTHOR
Brad Barden <perlmodules@5c30.org>
COPYRIGHT & LICENSE
Copyright (c) 2026 Brad Barden. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.