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

CONSTRUCTOR

new

my $kdf = Crypt::Sodium::XS::OO::kdf->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.

METHODS

PRIMITIVE

my $kdf = Crypt::Sodium::XS::OO::kdf->new;
my $default_primitive = $kdf->PRIMITIVE;

BYTES_MAX

my $subkey_max_length = $kdf->BYTES_MAX;

BYTES_MIN

my $subkey_min_length = $kdf->BYTES_MIN;

CONTEXTBYTES

my $context_length = $kdf->CONTEXTBYTES;

KEYBYTES

my $main_key_length = $kdf->KEYBYTES;

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 "BYTES_MIN" and "BYTES_MAX" (inclusive).

$context as an arbitrary string which is at least "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 "CONTEXTBYTES" in length. 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;

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:

  • 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.