Digest::Bcrypt(3pm)

💖 Digest::Bcrypt 💖

okay bestie, so this is the manual for Digest::Bcrypt, which is the Perl interface to the bcrypt digest algorithm — and it lives in the User Contributed Perl Documentation corner of your system. yes, the same bcrypt you've heard about in every "please hash your passwords" discourse thread. come sit with me. 🫶

---

🌸 NAME 🌸

Digest::Bcrypt — a Perl interface to the bcrypt digest algorithm. that's it, that's the whole vibe. 💅

---

✨ SYNOPSIS ✨

here's the whole thing, no edits, no notes:

#!/usr/bin/env perl
use strict;
use warnings;
use utf8;
use Digest;   # via the Digest module (recommended)

my $bcrypt = Digest->new('Bcrypt', cost => 12, salt => 'abcdefgh♥stuff');
# You can forego the cost and salt in favor of settings strings:
my $bcrypt = Digest->new('Bcrypt', settings => '$2a$20$GA.eY03tb02ea0DqbA.eG.');

# $cost is an integer between 5 and 31
$bcrypt->cost(12);

# $type is a selection between 2a, 2b, 2x, and 2y
$bcrypt->type('2b');

# $salt must be exactly 16 octets long
$bcrypt->salt('abcdefgh♥stuff');
# OR, for good, random salts:
use Data::Entropy::Algorithms qw(rand_bits);
$bcrypt->salt(rand_bits(16*8)); # 16 octets

# You can forego the cost and salt in favor of settings strings:
$bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.');

# add some strings we want to make a secret of
$bcrypt->add('some stuff', 'here and', 'here');

my $digest = $bcrypt->digest;
$digest = $bcrypt->hexdigest;
$digest = $bcrypt->b64digest;

# bcrypt's own non-standard base64 dictionary
$digest = $bcrypt->bcrypt_b64digest;

# Now, let's create a password hash and check it later:
use Data::Entropy::Algorithms qw(rand_bits);
my $bcrypt = Digest->new('Bcrypt', type => '2b', cost => 20, salt => rand_bits(16*8));
my $settings = $bcrypt->settings(); # save for later checks.
my $pass_hash = $bcrypt->add('Some secret password')->digest;

# much later, we can check a password against our hash via:
my $bcrypt = Digest->new('Bcrypt', settings => $settings);
if ($bcrypt->add($value_from_user)->digest eq $known_pass_hash) {
    say "Your password matched";
}
else {
    say "Try again!";
}

# Now that you've seen how cumbersome/silly that is,
# please use Crypt::Bcrypt instead of this module.

notice how that last comment literally says please use Crypt::Bcrypt instead of this module? yeah. we'll get to that. 🙈

---

💀 NOTICE 💀

so here's the tea, and it's important:

maintenance for Digest::Bcrypt will continue — it's not abandoned — but there is genuinely no reason to use Digest::Bcrypt when Crypt::Bcrypt already exists. they strongly suggest you use Crypt::Bcrypt instead.

and the reason? this Digest::Bcrypt interface is crufty and laborious to use when you compare it to Crypt::Bcrypt's interface. crufty. laborious. the manpage said it, not me. 😭

---

🌈 DESCRIPTION 🌈

Digest::Bcrypt gives you a Digest-based interface to the Crypt::Bcrypt library. that's the whole deal.

but okay, two things you MUST know before you go anywhere, because it will bite you:

• you have to set a "salt" that is exactly 16 octets long. not 15. not 17. sixteen. octets.
• you have to provide a "cost" in the range 1..31.

⚠️ lowkey memorize those two. the module will not be chill about it.

---

🎀 ATTRIBUTES 🎀

Digest::Bcrypt implements the following attributes. they're the knobs you get to turn. ✨

cost 💰

$bcrypt = $bcrypt->cost(20); # allows for method chaining
my $cost = $bcrypt->cost();

an integer in the range 5..31, and this one is required. no cost, no dice.

if you want the full lore on what "cost" even means inside the bcrypt algorithm, go read Crypt::Eksblowfish::Bcrypt — it explains it properly.

and when you call it with no arguments, it just hands you back the current cost. easy. 💅

salt 🧂

$bcrypt = $bcrypt->salt('abcdefgh♥stuff'); # allows for method chaining
my $salt = $bcrypt->salt();

# OR, for good, random salts:
use Data::Entropy::Algorithms qw(rand_bits);
$bcrypt->salt(rand_bits(16*8)); # 16 octets

this sets the value used as a salt. bcrypt requires exactly 16 octets of salt. that's the rule, that's the whole rule.

it is recommenced that you use a module like Data::Entropy::Algorithms to give you a truly randomized salt. (yes, the manpage spells it "recommenced". we respect the typo in this house. 💖)

when called with no arguments, it returns the current salt.

settings ⚙️

$bcrypt = $bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.'); # allows for method chaining
my $settings = $bcrypt->settings();

a "settings" string is the ✨convenience bundle✨ — it sets the "salt" in Digest::Bcrypt and the "cost" in Digest::Bcrypt automatically, all at once.

⚠️ heads up: setting the "settings" will override any current values in your "cost" and "salt" attributes. no merge, no compromise. settings wins.

for the fine print on what a "settings" string has to look like, please see Crypt::Eksblowfish::Bcrypt.

when called with no arguments, it returns the current settings string.

type 🦋

$bcrypt = $bcrypt->type('2b');
# method chaining on mutations
say $bcrypt->type(); # 2b

this sets the subtype of bcrypt in play. these subtypes are as defined in Crypt::Bcrypt. the available types are:

• "2b" — the current standard. 👑
• "2a" — older; it's the one used in Crypt::Eksblowfish.
• "2y" — considered equivalent to "2b", and used in PHP.
• "2x" — very broken and only needed to work with ancient PHP versions. (not me warning you. the manpage. 💀)

---

🧚 METHODS 🧚

Digest::Bcrypt inherits all methods from Digest::base and also implements/overrides the following methods as well. so it's got the family traits and its own little talents. 💅

new 🌱

my $bcrypt = Digest->new('Bcrypt', %params);
my $bcrypt = Digest::Bcrypt->new(%params);
my $bcrypt = Digest->new('Bcrypt', \%params);
my $bcrypt = Digest::Bcrypt->new(\%params);

creates a new "Digest::Bcrypt" object. it is recommended that you use the Digest module in the first example rather than using Digest::Bcrypt directly — that's the main character way to do it.

any of the "ATTRIBUTES" in Digest::Bcrypt above can be passed in as a parameter. go wild. 🌈

add ➕

$bcrypt->add("a"); $bcrypt->add("b"); $bcrypt->add("c");
$bcrypt->add("a")->add("b")->add("c");
$bcrypt->add("a", "b", "c");
$bcrypt->add("abc");

adds data to the message we're calculating the digest for. and the slay part? all the above examples have the same effect. pick whichever one speaks to you. periodt. ✨

b64digest 🔤

my $digest = $bcrypt->b64digest;

same as "digest", but it returns the digest base64 encoded.

the "length" of the returned string will be 31, and it will only contain characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '/'.

and ngl, the base64 encoded string returned is not padded to be a multiple of 4 bytes long. that's just how it is here.

bcrypt_b64digest 🔡

my $digest = $bcrypt->bcrypt_b64digest;

same as "digest", but it returns the digest base64 encoded using the alphabet that is commonly used with bcrypt.

the "length" of the returned string will be 31, and it will only contain characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '.'.

this one also is not padded to be a multiple of 4 bytes long.

⚠️ note: this is bcrypt's own non-standard base64 alphabet. it is not compatible with the standard MIME base64 encoding. do not mix them up, bestie, i'm begging. 😭

clone 👯

my $clone = $bcrypt->clone;

creates a clone of the "Digest::Bcrypt" object, and returns it. twinning! 🫶

digest 💾

my $digest = $bcrypt->digest;

returns the binary digest for the message. the returned string will be 23 bytes long.

hexdigest 🔢

my $digest = $bcrypt->hexdigest;

same as "digest", but it returns the digest in hexadecimal form.

the "length" of the returned string will be 46, and it will only contain characters from the ranges '0'..'9' and 'a'..'f'. lowercase only, diva. 💅

reset 🔄

$bcrypt->reset;

resets the object to the same internal state it was in when it was constructed. factory settings, basically. fresh start, no baggage. ✨

---

👀 SEE ALSO 👀

• Digest
• Crypt::Eksblowfish::Bcrypt
• Data::Entropy::Algorithms

---

👑 AUTHOR 👑

James Aitken jaitken@cpan.org

---

💜 CONTRIBUTORS 💜

• Chase Whitener capoeira@cpan.org

---

📜 COPYRIGHT AND LICENSE 📜

this software is copyright (c) 2012 by James Aitken.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

---

and that's the whole page, bestie!! 🎀 this was Digest::Bcrypt(3pm) from the User Contributed Perl Documentation, running on perl v5.32.1, dated 2022-01-22 — so go forth, set your "cost", guard your 16 octets of "salt", and maybe... consider Crypt::Bcrypt like the manpage so desperately asked you to. 💖🦋✨