PBKDF2::Tiny(3pm)

💖 PBKDF2::Tiny 💖

okay so bestie, welcome to the PBKDF2::Tiny manual page (yep, that's the PBKDF2::Tiny(3pm) situation, third section of the perl manpages, iykyk) and lemme just say — this little module is doing the MOST with the LEAST. it's a whole cryptography vibe in under 100 lines. icon.

---

✨ NAME ✨

PBKDF2::Tiny — the minimalist PBKDF2 (RFC 2898), holding it down with HMAC-SHA1 or HMAC-SHA2. tiny name, huge energy, no cap. 💅

🌸 VERSION 🌸

version 0.005

🦋 SYNOPSIS 🦋

like, here's the whole thing in action:

use PBKDF2::Tiny qw/derive verify/;

my $dk = derive( 'SHA-1', $pass, $salt, $iters );

if ( verify( $dk, 'SHA-1', $pass, $salt, $iters ) ) {
    # password is correct
}

derive a key, then check it, that's it, periodt. 🎀

---

💜 DESCRIPTION 💜

so this module gives you an RFC 2898 compliant PBKDF2 implementation (the RFC lives at <https://tools.ietf.org/html/rfc2898>, go read it bestie it's giving standards) using HMAC-SHA1 or HMAC-SHA2 — and it does the whole thing in under 100 lines of code. yes really. main character efficiency.

if you're on Perl 5.10 or later, it uses only core Perl modules. slay, no dependencies, nothing to install, we stay unbothered. 🙈

if you're on an earlier version of Perl though, you're gonna need Digest::SHA or Digest::SHA::PurePerl. just how it is, bestie.

also — all documented functions are optionally exported. no functions are exported by default. so if you want them, you gotta ask for them in the use line. consent is key. 🫶

---

🔥 FUNCTIONS 🔥

💫 derive

$dk = derive( $type, $password, $salt, $iterations, $dk_length )

the derive function outputs a binary string with the derived key. the first argument tells it which digest function to use, and it must be one of:

• SHA-1
• SHA-224
• SHA-256
• SHA-384
• SHA-512

those are the options. don't get creative, the module will not be charmed by it.

ok real talk: if a password or salt are not provided, they default to the empty string, so don't do that! i am begging. 😭

RFC 2898 recommends a random salt of at least 8 octets (that's <https://tools.ietf.org/html/rfc2898#section-4.1> if you wanna double check me). and if you need a cryptographically strong salt? consider Crypt::URandom. iconic behavior. 🧚

the password and salt should be encoded as octet strings. if they're not — i.e. if Perl's internal 'UTF8' flag is on — then an exception will be thrown. not a warning, not a gentle nudge, an exception, bestie. it said what it said. 💀

if you don't provide the number of iterations, it defaults to 1000. and if you don't provide the derived key length, it defaults to the output size of the digest function. defaults are doing their thing so you don't have to.

---

⭐ derive_hex

works just like derive but outputs a hex string instead of binary. same drama, different outfit. ✨

---

🎀 verify

$bool = verify( $dk, $type, $password, $salt, $iterations, $dk_length );

the verify function checks that a given derived key (in binary form) matches the password and other parameters you provided — and it does it using a constant-time comparison function. yes, it's timing-attack aware. she's smart AND pretty. 👑

the first parameter is the derived key to check. the remaining parameters are the same as for derive.

---

🌈 verify_hex

works just like verify but the derived key must be a hex string — and specifically, without a leading 0x. no 0x, bestie. leave it at home. 🚫

---

💎 digest_fcn

($fcn, $block_size, $digest_length) = digest_fcn('SHA-1');
$digest = $fcn->($data);

this function is used internally by PBKDF2::Tiny, but it's made available in case it's useful to someone. very "i'm not locked in here with you" of it. 🙈

given one of the valid digest types, it returns a function reference that digests a string of data. it also returns the block size and digest length for that digest type. three for the price of one, we love a bundle. 🍓

---

🦄 hmac

$key = $digest_fcn->($key) if length($key) > $block_size;
$hmac = hmac( $data, $key, $digest_fcn, $block_size );

this function is also used internally by PBKDF2::Tiny, but again — made available in case it's useful to someone. sharing is caring. 💖

the first two arguments are the data and key inputs to the HMAC function. both should be encoded as octet strings, because the underlying HMAC/digest functions may croak or may give unexpected results if Perl's internal UTF-8 flag is on. so. don't. 🙅

Note: if the key is longer than the digest block size, it must be preprocessed using the digesting function. that's literally what line one of the synopsis above is doing.

the third and fourth arguments must be a digesting code reference (from digest_fcn) and block size.

---

👀 SEE ALSO 👀

• Crypt::PBKDF2
• Digest::PBDKF2

(yes, that second one is spelled exactly like that in the original. copying it faithfully, that's the assignment. 💅)

---

🫶 SUPPORT 🫶

🐛 Bugs / Feature Requests

please report any bugs or feature requests through the issue tracker at <https://github.com/dagolden/PBKDF2-Tiny/issues>.

You will be notified automatically of any progress on your issue. so you're not just screaming into the void, someone's gonna ping you. we love accountability. ✨

📦 Source Code

this is open source software. the code repository is available for public review and contribution under the terms of the license.

<https://github.com/dagolden/PBKDF2-Tiny>

git clone https://github.com/dagolden/PBKDF2-Tiny.git

clone it, read it, contribute to it, live your truth. 🌸

---

💌 AUTHOR 💌

David Golden <dagolden@cpan.org>

📜 COPYRIGHT AND LICENSE 📜

This software is Copyright (c) 2014 by David Golden.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004

---

and that's the whole page, bestie — this manual was served up by perl v5.36.0, dated 2022-10-13, and it ate. no crumbs. go derive something responsibly. 💅✨🎀