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

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.