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_length = 32;
my $master_key = kdf_keygen();
my $subkey_1 = kdf_derive($master_key, 1, $output_key_length, $context);
my $subkey_2 = kdf_derive($master_key, 2, $output_key_length, $context);
my $subkey_3 = kdf_derive($master_key, 54321, $output_key_length, $context);

DESCRIPTION

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.

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.

FUNCTIONS

Nothing is exported by default. A :default tag imports the functions and constants as documented below. A separate import tag is provided for each of the primitives listed in "PRIMITIVES". For example, :blake2b imports kdf_blake2b_derive. You should use at least one import tag.

kdf_derive

my $subkey = kdf_derive($key, $id, $subkey_len, $context);

$key is the master key from which others should be derived.

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

$subkey_len is the desired length of the subkey output. This can be used to derive a key of the particular length needed for the primitive with which the subkey will be used. It must be between "kdf_BYTES_MIN" and "kdf_BYTES_MAX" (inclusive).

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

WARNING: $context must be at least "kdf_CONTEXTBYTES" in length. 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 has as $context.

kdf_keygen

my $key = kdf_keygen();

CONSTANTS

kdf_PRIMITIVE

my $default_primitive = kdf_PRIMITIVE();

kdf_BYTES_MAX

my $subkey_max_length = kdf_BYTES_MAX();

kdf_BYTES_MIN

my $subkey_min_length = kdf_BYTES_MIN();

kdf_CONTEXTBYTES

my $context_length = kdf_CONTEXTBYTES();

kdf_KEYBYTES

my $main_key_length = kdf_KEYBYTES();

PRIMITIVES

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

• blake2b

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:

• IRC channel #sodium on irc.perl.org.

• Email the author directly.

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.

cpanm Crypt::Sodium::XS

perl -MCPAN -e shell
install Crypt::Sodium::XS