/ 
Crypt-Sodium-XS-0.000038
River stage zero No dependents
/ Crypt::Sodium::XS::kdf

NAME

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

SYNOPSIS

use Crypt::Sodium::XS::kdf ":default";

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.

FUNCTIONS

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 kdf_<primitive>_* functions and constants for that primitive. A :all tag imports everything.

kdf_derive

kdf_<primitive>_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 "kdf_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. It must be less than "kdf_DERIVE_ID_CEILING" (see note below). 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 "kdf_BYTES_MIN" to "kdf_BYTES_MAX", inclusive.

$context is optional. It is an arbitrary string which is at least "kdf_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.

Note: $id is limited to one less than "kdf_DERIVE_ID_CEILING". This limitation is applied on all platforms to prevent accidental derivation of duplicate keys due to handling of numeric values in perl. In perl, it is possible to lose numeric precision above 2 ** 53 (when a number is stored and operated upon as NV; a double). This is always the case on 32-bit systems, but can happen to numeric values on 64-bit systems as well depending on the context of the perl code. Example from a 64-bit system (if this limitation were not in place):

my $k = "\0" x kdf_KEYBYTES(); # null key
my $x = 2 ** 53 - 2;
kdf_derive($k, $x++, 32)->to_base64->unlock for (1 .. 6);
# output:
# rHfr3QmtE_SSsGozwo9C1Ho24quHYMZqsu4Ax6KK_e0
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc <--- note that this is 2 ** 53
# v4sP0CLKMBbKmxvpG4IHzZui-5cTCozjJu57GdNB3ac
# Ual0mve2EEwqAh2Uqpa7dMUNyWslVb-kFWUIdnVrdcw <--- note again, 2 ** 53 + 2
# AbYjao-tEhLyFzPvmmk1viGummBid5MrN3kczzFm1TE
# rRVOLHdBIXVk6gWPHjCsjXGz-SERFUUne3_9TMtX2Vw <--- note again, 2 ** 53 + 4
$x = 2 ** 53;
kdf_derive($k, $x++, 32)->to_base64->unlock for (1 .. 5);
# output:
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc <--- 2 ** 53
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc
# ixpuCXMoYQ15uBk_ZzFbHqH_qVQGywke-uBmutPPjcc
$x += 2;  # adding 1 just repeats the above behavior
kdf_derive($k, $x++, 32)->to_base64->unlock for (1 .. 5);
# Ual0mve2EEwqAh2Uqpa7dMUNyWslVb-kFWUIdnVrdcw <--- 2 ** 53 + 2
# rRVOLHdBIXVk6gWPHjCsjXGz-SERFUUne3_9TMtX2Vw <--- 2 ** 53 + 4
# rRVOLHdBIXVk6gWPHjCsjXGz-SERFUUne3_9TMtX2Vw
# rRVOLHdBIXVk6gWPHjCsjXGz-SERFUUne3_9TMtX2Vw
# rRVOLHdBIXVk6gWPHjCsjXGz-SERFUUne3_9TMtX2Vw

WARNING: $context must be at least "kdf_CONTEXTBYTES" bytes. If it is longer than this, only the first "kdf_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 hash as $context.

kdf_keygen

kdf_<primitive>_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.

CONSTANTS

kdf_PRIMITIVE

my $default_primitive = kdf_PRIMITIVE();

Returns the name of the default primitive.

kdf_BYTES_MAX

kdf_<primitive>_BYTES_MAX

my $subkey_max_size = kdf_BYTES_MAX();

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

kdf_BYTES_MIN

kdf_<primitive>_BYTES_MIN

my $subkey_min_size = kdf_BYTES_MIN();

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

kdf_CONTEXTBYTES

kdf_<primitive>_CONTEXTBYTES

my $context_size = kdf_CONTEXTBYTES();

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

kdf_KEYBYTES

kdf_<primitive>_KEYBYTES

my $main_key_size = kdf_KEYBYTES();

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

kdf_DERIVE_ID_CEILING

die "cannot use this id" unless ($id < kdf_DERIVE_ID_CEILING());

Returns one more than the maximum usable id for "derive".

Note: This is specific to Crypt::Sodium::XS; it is not a libsodium constant.

PRIMITIVES

All constants (except _PRIMITIVE) and functions have kdf_<primitive>-prefixed couterparts (e.g., kdf_blake2b_derive, kdf_blake2b_BYTES_MIN).

  • blake2b (default)

SEE ALSO

Crypt::Sodium::XS
Crypt::Sodium::XS::OO::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.