Crypt::PBKDF2(3pm)

📦
version 0.261630 · 12 versions
, in arch rolling

🎀 Crypt::PBKDF2 — the PBKDF2 password hashing algorithm 🎀

Okay bestie, so this page is the manual for Crypt::PBKDF2 (that's the Perl module, from the User Contributed Perl Documentation section of your man pages, iykyk). Version? version 0.261630. Slay. Let's get into it 💅

✨ SYNOPSIS ✨

Here's the vibe in code, literally exactly how you'd use it:

use Crypt::PBKDF2;

my $pbkdf2 = Crypt::PBKDF2->new(
    hash_class => 'HMACSHA2', # this is the default (HMAC-SHA256)
    iterations => 600000,     # so is this
    output_len => 32,         # and this
    salt_len => 4,            # and this.
);

my $hash = $pbkdf2->generate("s3kr1t_password");
if ($pbkdf2->validate($hash, "s3kr1t_password")) {
    access_granted();
}

Like… make the hash, check the hash, let them in. That's the whole plot 🫶

🌸 DESCRIPTION 🌸

So PBKDF2 is a secure password hashing algorithm, and the way it works is by using "key strengthening" techniques to make the complexity of a brute-force attack arbitrarily high — you can crank it as hard as you want, no cap 🔥

It uses any other cryptographic hash or cipher (by convention, usually HMAC-SHA1, but Crypt::PBKDF2 is fully pluggable, main character energy), and it lets you pick an arbitrary number of iterations of the hashing function, plus a nearly unlimited output hash size — we're talking up to 2**32 - 1 times the size of the output of the backend hash, which is honestly iconic.

And obviously the hash is salted, as any password hash should be (periodt), and the salt may also be of arbitrary size 💖

🦋 ATTRIBUTES 🦋

hash_class

Type: String, Default: HMACSHA2

This is the name of the default class that provides PBKDF2's Pseudo-Random Function (the backend hash, bestie). Here's the little trick: if the value starts with a "+", the "+" gets removed and the remainder is taken as a fully-qualified package name. Otherwise, the value gets appended to "Crypt::PBKDF2::Hash::".

The default class is "HMACSHA2", which (with its own default "sha_size" of 256) gives you HMAC-SHA256. Chef's kiss 👑

hash_args

Type: HashRef, Default: {}

Arguments to be passed to the "hash_class" constructor. That's it, that's the whole thing 🎀

hasher

Type: Object (must fulfill role Crypt::PBKDF2::Hash), Default: None.

You can also just… hand it a hash object directly, bestie. In that case "hash_class" and "hash_args" are ignored. Rude but valid 💅

iterations

Type: Integer, Default: 600000.

The default number of iterations of the hashing function to use for the "generate" and "PBKDF2" methods. Six hundred thousand little rounds of love 🌈

output_len

Type: Integer.

The default size (in bytes, not bits — don't embarrass yourself) of the output hash. If you don't provide a value, the output size depends on the "hash_class" / "hasher" you selected, and it'll equal the output size of the backend hash (e.g. 20 bytes for HMACSHA1).

salt_len

Type: Integer, Default: 4

The default salt length (in bytes) for the "generate" method. Tiny but mighty 🍓

encoding

Type: String (either "crypt" or "ldap"), Default: "ldap"

The hash format to generate. So the "ldap" format is intended to be compatible with RFC2307, and it looks like this:

{X-PBKDF2}HMACSHA1:AAAD6A:8ODUPA==:1HSdSVVwlWSZhbPGO7GIZ4iUbrk=

While the "crypt" format is similar to the format used by the crypt() function — except with more structured information in the second (salt) field. And it looks like:

$PBKDF2$HMACSHA1:1000:4q9OTg==$9Pb6bCRgnct/dga+4v4Lyv8x31s=
Bestie, listen: versions of this module up to 0.110461 generated the "crypt" format, so set that if you want it. Current versions will read either format, but the "ldap" format is preferred. 💖

length_limit

Type: Integer

The maximum password length to allow, for generate and verify functions.

⚠️ Okay this one matters: allowing passwords of unlimited length can allow a denial-of-service attack in which an attacker asks the server to validate very large passwords. Not cute. Not the vibe.

For compatibility this attribute is unset by default, but it's recommended to set it to a reasonably small value like 100 — large enough that users aren't discouraged from having secure passwords, but small enough to limit the computation needed to validate any one password. Balance, bestie 🧚

💜 METHODS 💜

generate ($password, [$salt])

Generates a hash for the given $password. If $salt is not provided, a random salt with length "salt_len" will be generated. Random salt = good salt ✨

There are two output formats available, depending on the setting of the "encoding" attribute: "ldap" and "crypt" — go peek at the docs for "encoding" for more info.

validate ($hashed, $password)

Validates whether the password $password matches the hash string $hashed. May throw an exception if the format of $hashed is invalid; otherwise, returns true or false. It accepts both formats that the "generate" method can produce, so you're covered either way 🫶

PBKDF2 ($salt, $password)

The raw PBKDF2 algorithm, no filter, no makeup. Given the $salt and $password, returns the raw binary hash. Raw. Binary. Iconic.

PBKDF2_base64 ($salt, $password)

Same as the "PBKDF2" method, only the output is encoded with MIME::Base64. Cute little encoding moment 🎀

PBKDF2_hex ($salt, $password)

Same as the "PBKDF2" method, only the output is encoded in hexadecimal. 0-9a-f supremacy 💅

encode_string ($salt, $hash)

Given a generated salt and hash, generates output in the form generated by "generate" and accepted by "validate". Unlikely to be of much use to anyone else, ngl — but it's there 💖

decode_string ($hashed)

Given a textual hash in the form generated by "generate", decodes it and returns a HashRef containing:

  • "algorithm": A string representing the hash algorithm used. See "hasher_from_algorithm ($algo_str)".
  • "iterations": The number of iterations used.
  • "salt": The salt, in raw binary form.
  • "hash": The hash, in raw binary form.

This method is mostly for internal use, but it's been left public since it may come in handy. If the input data is invalid, it may throw an exception ⭐

hasher_from_algorithm ($algo_str)

Attempts to load and instantiate a "Crypt::PBKDF2::Hash::*" class based on an algorithm string as produced by "encode_string" / "generate". It's giving matchmaker, honestly 🌸

clone (%params)

Create a new object like this one, but with %params changed. Same vibe, different settings 🦋

🔥 SEE ALSO 🔥

Go read them, bestie, it's good for you 📚

👑 AUTHOR 👑

Andrew Rodland <andrew@cleverdomain.org> — thank you for your service, king 🫡

This software is copyright (c) 2026 by Andrew Rodland.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. Free software, free spirit, fr fr 🕊️

✨ and that's the whole page, bestie ✨ — this little number came from perl v5.42.2, dated 2026-08-07, and it's the Crypt::PBKDF2(3pm) man page. Go forth and hash responsibly 💅🎀

📦 where this page comes from