/ 
Crypt-Sodium-XS-0.000032
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. 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.

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 has 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();

kdf_BYTES_MIN

kdf_<primitive>_BYTES_MIN

my $subkey_min_size = kdf_BYTES_MIN();

kdf_CONTEXTBYTES

kdf_<primitive>_CONTEXTBYTES

my $context_size = kdf_CONTEXTBYTES();

kdf_KEYBYTES

kdf_<primitive>_KEYBYTES

my $main_key_size = kdf_KEYBYTES();

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.