Crypt:...Bcrypt(3pm)

📦
version 0.009 · 13 versions
, in ubuntu stonking

💅 Crypt::Eksblowfish::Bcrypt — the manual, but make it make sense

okay bestie so this page is officially Crypt::Eksblowfish::Bcrypt(3pm), filed under User Contributed Perl Documentation, and it's genuinely one of the most iconic crypto modules out here. we're talking real ✨ bcrypt ✨ energy. let's get into it.

🌸 NAME 🌸

Crypt::Eksblowfish::Bcrypt — the Blowfish-based Unix crypt() password hash. it's giving secure, it's giving password-hashing royalty, no cap 💖

✨ SYNOPSIS ✨

here's the whole vibe in code, literally copy-paste-able:

        use Crypt::Eksblowfish::Bcrypt qw(bcrypt_hash);

        $hash = bcrypt_hash({
                        key_nul => 1,
                        cost => 8,
                        salt => $salt,
                }, $password);

        use Crypt::Eksblowfish::Bcrypt qw(en_base64 de_base64);

        $text = en_base64($octets);
        $octets = de_base64($text);

        use Crypt::Eksblowfish::Bcrypt qw(bcrypt);

        $hashed_password = bcrypt($password, $settings);

see how there's three whole doors into this module? bcrypt_hash, the base 64 twins, and bcrypt itself. pick your fighter 🎀

🦋 DESCRIPTION 🦋

so this module implements the Blowfish-based Unix crypt() password hashing algorithm, which everyone calls "bcrypt". and here's the tea: the hash uses a variant of Blowfish called "Eksblowfish", and the whole point of that variant is that it was modified to have particularly expensive key scheduling. expensive on purpose, bestie. that's the security feature, not a bug 💀

Eksblowfish and bcrypt were devised by Niels Provos and David Mazieres for OpenBSD, and the design is described in a paper at <http://www.usenix.org/events/usenix99/provos.html> — go read it, it ate 🔥

👑 FUNCTIONS 👑

bcrypt_hash(SETTINGS, PASSWORD)

Hashes PASSWORD according to the supplied SETTINGS, and returns the 23-octet hash. yes, exactly twenty-three, don't @ me.

SETTINGS must be a reference to a hash, with these keys — and literally all three of them matter:

  • key_nul — a truth value: whether to append a NUL to the password before using it as a key. so here's the lore: the algorithm as originally devised does not do this, but it was later modified to do it. the version that does append NUL is the one to be preferred 🫶 — not doing so is supported only for backward compatibility. so like, it works, but it's giving legacy.
  • cost — a non-negative integer controlling the cost of the hash function. the number of operations is proportional to 2^cost. so yeah, bigger cost = more pain = more better (but slower, obviously).
  • salt — exactly sixteen octets of salt. sixteen. octets. that's the rule 🌸

en_base64(BYTES)

Encodes the octet string textually using the form of base 64 that is conventionally used with bcrypt. that specific flavor of base 64, not the regular one, iykyk 💅

de_base64(TEXT)

Decodes an octet string that was textually encoded using the form of base 64 that is conventionally used with bcrypt. it's the reverse of the above, the little mirror 🪞

bcrypt(PASSWORD, SETTINGS)

this is the main character. it's a version of crypt (see "crypt" in perlfunc) that implements the bcrypt algorithm. it does not implement any other hashing algorithms, so if you want others, you're gonna have to examine the algorithm prefix in SETTINGS and dispatch between more than one version of crypt yourself. it does one job and it does it gorgeously ✨

SETTINGS must be a string which encodes the algorithm parameters, including salt. and the format is strict, bestie, listen up:

  • it must begin with $2
  • then optional a
  • then $
  • then two digits
  • then $
  • then 22 base 64 digits

the rest of the string is ignored. and what do those pieces mean?

  • the presence of the optional a means that a NUL is to be appended to the password before it is used as a key.
  • the two digits set the cost parameter.
  • the 22 base 64 digits encode the salt.
⚠️ the function will die if SETTINGS does not have this format. like, it is not playing around. format it right or catch the 💀.

the PASSWORD is hashed according to the SETTINGS. the value returned is a string which encodes the algorithm parameters and the hash: the parameters are in the same format required in SETTINGS, and the hash is appended in the form of 31 base 64 digits.

and this is the cute part — that result is suitable to be used as a SETTINGS string for input to this function, because the hash part of the string is ignored on input. so it round-trips. it's giving self-sufficient queen 👑

💜 SEE ALSO 💜

🌈 AUTHOR 🌈

Andrew Main (Zefram) <zefram@fysh.org> — absolute legend, we stan 🫶

Copyright (C) 2006, 2007, 2008, 2009, 2010, 2011 Andrew Main (Zefram) <zefram@fysh.org>

⭐ LICENSE ⭐

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. free as in freedom, slay 💖

okay that's the whole page!! this was Crypt::Eksblowfish::Bcrypt(3pm) from perl v5.42.3, dated 2026-08-19, and honestly? iconic manual, no notes. go hash something responsibly bestie 🌸🦋💅

📦 where this page comes from