/ 
Crypt-Sodium-XS-0.000031
/ Crypt::Sodium::XS::OO::kdf
Security Advisories (2)
CVE-2025-15444 (2026-01-06)

Crypt::Sodium::XS module versions prior to 0.000042, for Perl, include a vulnerable version of libsodium libsodium <= 1.0.20 or a version of libsodium released before December 30, 2025 contains a vulnerability documented as CVE-2025-69277  https://www.cve.org/CVERecord?id=CVE-2025-69277 . The libsodium vulnerability states: In atypical use cases involving certain custom cryptography or untrusted data to crypto_core_ed25519_is_valid_point, mishandles checks for whether an elliptic curve point is valid because it sometimes allows points that aren't in the main cryptographic group. 0.000042 includes a version of libsodium updated to 1.0.20-stable, released January 3, 2026, which includes a fix for the vulnerability.

CVE-2026-30910 (2026-03-08)

Crypt::Sodium::XS versions through 0.001000 for Perl has potential integer overflows. Combined aead encryption, combined signature creation, and bin2hex functions do not check that output size will be less than SIZE_MAX, which could lead to integer wraparound causing an undersized output buffer. This can cause a crash in bin2hex and encryption algorithms other than aes256gcm. For aes256gcm encryption and signatures, an undersized buffer could lead to buffer overflow. Encountering this issue is unlikely as the message length would need to be very large. For bin2hex the input size would have to be > SIZE_MAX / 2 For aegis encryption the input size would need to be > SIZE_MAX - 32U For other encryption the input size would need to be > SIZE_MAX - 16U For signatures the input size would need to be > SIZE_MAX - 64U

NAME

Crypt::Sodium::XS::OO::kdf - Secret subkey derivation from a main secret key

SYNOPSIS

use Crypt::Sodium::XS;

my $kdf = Crypt::Sodium::XS->kdf;

my $context = "see notes below about context strings";
my $output_key_size = 32;
my $master_key = $kdf->keygen;
my $subkey_1 = $kdf->derive($master_key, 1, $output_key_size, $context);
my $subkey_2 = $kdf->derive($master_key, 2, $output_key_size, $context);
my $subkey_3 = $kdf->derive($master_key, 54321, $output_key_size, $context);

DESCRIPTION

Multiple secret subkeys can be derived from a single high-entropy master key. Given the master key and a numeric key identifier, a subkey can be deterministically computed. However, given a subkey, an attacker cannot compute the master key nor any other subkeys.

Note: Secret keys used to encrypt or sign confidential data have to be chosen from a very large keyspace. However, passwords are usually short, human-generated strings, making dictionary attacks practical. If you are intending to derive keys from a password, see Crypt::Sodium::XS::pwhash instead.

CONSTRUCTOR

new

my $kdf = Crypt::Sodium::XS::OO::kdf->new(primitive => 'blake2b');
my $kdf = Crypt::Sodium::XS->kdf;

Returns a new kdf object for the given primitive. If not given, the default primitive is default.

ATTRIBUTES

primitive

my $primitive = $kdf->primitive;
$kdf->primitive('blake2b');

Gets or sets the primitive used for all operations by this object. Note this can be default.

METHODS

primitives

my @primitives = Crypt::Sodium::XS::OO::kdf->primitives;
my @primitives = $kdf->primitives;

Returns a list of all supported primitive names, including default.

Can be called as a class method.

PRIMITIVE

my $primitive = $kdf->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.

derive

my $subkey = $kdf->derive($key, $id, $subkey_size, $context, $flags);

$key is the master key from which others should be derived. It must be "KEYBYTES" bytes. It may be a Crypt::Sodium::XS::MemVault.

$id is an unsigned integer signifying the numeric identifier of the subkey which is being derived. The same $key, $id, $subkey_size, and $context will always derive the same key.

$subkey_size is the size, in bytes, of the subkey output. This can be used to derive a key of the particular size needed for the primitive with which the subkey will be used. It must be in the range of "BYTES_MIN" to "BYTES_MAX", inclusive.

$context is optional. It is an arbitrary string which is at least "CONTEXTBYTES" bytes (see warning below). This can be used to create an application-specific tag, such that using the same $key, $id, and $subkey_size can still derive a different subkey.

$flags is optional. It is the flags used for the $subkey Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

WARNING: $context must be at least "CONTEXTBYTES" bytes. If it is longer than this, only the first "CONTEXTBYTES" bytes will be used. As this gives a limited range of use (application-specific strings might be likely to have the same first 8 bytes), it is recommended to use an arbitrary-length string as the input to a hash function (e.g., "generichash" in Crypt::Sodium::XS::generichash or "shorthash" in Crypt::Sodium::XS::shorthash) and use the output has as $context.

keygen

my $key = $kdf->keygen($flags);

$flags is optional. It is the flags used for the $key Crypt::Sodium::XS::MemVault. See Crypt::Sodium::XS::ProtMem.

Returns a Crypt::Sodium::XS::MemVault: a master key of "KEYBYTES" bytes.

BYTES_MAX

my $subkey_max_size = $kdf->BYTES_MAX;

Returns the maximum size, in bytes, of a generated subkey.

BYTES_MIN

my $subkey_min_size = $kdf->BYTES_MIN;

Returns the minimum size, in bytes, of a generated subkey.

CONTEXTBYTES

my $context_size = $kdf->CONTEXTBYTES;

Returns the size, in bytes, of a context string.

KEYBYTES

my $main_key_size = $kdf->KEYBYTES;

Returns the size, in bytes, of a master key.

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::kdf
https://doc.libsodium.org/key_derivation

FEEDBACK

For reporting bugs, giving feedback, submitting patches, etc. please use the following:

AUTHOR

Brad Barden <perlmodules@5c30.org>

COPYRIGHT & LICENSE

Copyright (c) 2022 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.