1Digest::Bcrypt(3)     User Contributed Perl Documentation    Digest::Bcrypt(3)
2
3
4

NAME

6       Digest::Bcrypt - Perl interface to the bcrypt digest algorithm
7

SYNOPSIS

9           #!/usr/bin/env perl
10           use strict;
11           use warnings;
12           use utf8;
13           use Digest;   # via the Digest module (recommended)
14
15           my $bcrypt = Digest->new('Bcrypt', cost => 12, salt => 'abcdefgh♥stuff');
16           # You can forego the cost and salt in favor of settings strings:
17           my $bcrypt = Digest->new('Bcrypt', settings => '$2a$20$GA.eY03tb02ea0DqbA.eG.');
18
19           # $cost is an integer between 1 and 31
20           $bcrypt->cost(12);
21
22           # $salt must be exactly 16 octets long
23           $bcrypt->salt('abcdefgh♥stuff');
24           # OR, for good, random salts:
25           use Data::Entropy::Algorithms qw(rand_bits);
26           $bcrypt->salt(rand_bits(16*8)); # 16 octets
27
28           # You can forego the cost and salt in favor of settings strings:
29           $bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.');
30
31           # add some strings we want to make a secret of
32           $bcrypt->add('some stuff', 'here and', 'here');
33
34           my $digest = $bcrypt->digest;
35           $digest = $bcrypt->hexdigest;
36           $digest = $bcrypt->b64digest;
37
38           # bcrypt's own non-standard base64 dictionary
39           $digest = $bcrypt->bcrypt_b64digest;
40
41           # Now, let's create a password hash and check it later:
42           use Data::Entropy::Algorithms qw(rand_bits);
43           my $bcrypt = Digest->new('Bcrypt', cost=>20, salt=>rand_bits(16*8));
44           my $settings = $bcrypt->settings(); # save for later checks.
45           my $pass_hash = $bcrypt->add('Some secret password')->digest;
46           # much later, we can check a password against our hash via:
47           my $bcrypt = Digest->new('Bcrypt', settings=>$settings);
48           if ($bcrypt->add($value_from_user)->digest eq $known_pass_hash) {
49               say "Your password matched";
50           }
51           else {
52               say "Try again!";
53           }
54

NOTICE

56       While maintenance for Digest::Bcrypt will continue, there's no reason
57       to use Digest::Bcrypt when Crypt::Eksblowfish::Bcrypt already exists.
58       We suggest that you use Crypt::Eksblowfish::Bcrypt instead.
59

DESCRIPTION

61       Digest::Bcrypt provides a Digest-based interface to the
62       Crypt::Eksblowfish::Bcrypt library.
63
64       Please note that you must set a "salt" of exactly 16 octets in length,
65       and you must provide a "cost" in the range 1..31.
66

ATTRIBUTES

68       Digest::Bcrypt implements the following attributes.
69
70   cost
71           $bcrypt = $bcrypt->cost(20); # allows for method chaining
72           my $cost = $bcrypt->cost();
73
74       An integer in the range 1..31, this is required.
75
76       See Crypt::Eksblowfish::Bcrypt for a detailed description of "cost" in
77       the context of the bcrypt algorithm.
78
79       When called with no arguments, it will return the current cost.
80
81   salt
82           $bcrypt = $bcrypt->salt('abcdefgh♥stuff'); # allows for method chaining
83           my $salt = $bcrypt->salt();
84
85           # OR, for good, random salts:
86           use Data::Entropy::Algorithms qw(rand_bits);
87           $bcrypt->salt(rand_bits(16*8)); # 16 octets
88
89       Sets the value to be used as a salt. Bcrypt requires exactly 16 octets
90       of salt.
91
92       It is recommenced that you use a module like Data::Entropy::Algorithms
93       to provide a truly randomized salt.
94
95       When called with no arguments, it will return the current salt.
96
97   settings
98           $bcrypt = $bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.'); # allows for method chaining
99           my $settings = $bcrypt->settings();
100
101       A "settings" string can be used to set the "salt" in Digest::Bcrypt and
102       "cost" in Digest::Bcrypt automatically. Setting the "settings" will
103       override any current values in your "cost" and "salt" attributes.
104
105       For details on the "settings" string requirements, please see
106       Crypt::Eksblowfish::Bcrypt.
107
108       When called with no arguments, it will return the current settings
109       string.
110

METHODS

112       Digest::Bcrypt inherits all methods from Digest::base and
113       implements/overrides the following methods as well.
114
115   new
116           my $bcrypt = Digest->new('Bcrypt', %params);
117           my $bcrypt = Digest::Bcrypt->new(%params);
118           my $bcrypt = Digest->new('Bcrypt', \%params);
119           my $bcrypt = Digest::Bcrypt->new(\%params);
120
121       Creates a new "Digest::Bcrypt" object. It is recommended that you use
122       the Digest module in the first example rather than using Digest::Bcrypt
123       directly.
124
125       Any of the "ATTRIBUTES" in Digest::Bcrypt above can be passed in as a
126       parameter.
127
128   add
129           $bcrypt->add("a"); $bcrypt->add("b"); $bcrypt->add("c");
130           $bcrypt->add("a")->add("b")->add("c");
131           $bcrypt->add("a", "b", "c");
132           $bcrypt->add("abc");
133
134       Adds data to the message we are calculating the digest for. All the
135       above examples have the same effect.
136
137   b64digest
138           my $digest = $bcrypt->b64digest;
139
140       Same as "digest", but will return the digest base64 encoded.
141
142       The "length" of the returned string will be 31 and will only contain
143       characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '/'
144
145       The base64 encoded string returned is not padded to be a multiple of 4
146       bytes long.
147
148   bcrypt_b64digest
149           my $digest = $bcrypt->bcrypt_b64digest;
150
151       Same as "digest", but will return the digest base64 encoded using the
152       alphabet that is commonly used with bcrypt.
153
154       The "length" of the returned string will be 31 and will only contain
155       characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '.'
156
157       The base64 encoded string returned is not padded to be a multiple of 4
158       bytes long.
159
160       Note: This is bcrypt's own non-standard base64 alphabet, It is not
161       compatible with the standard MIME base64 encoding.
162
163   clone
164           my $clone = $bcrypt->clone;
165
166       Creates a clone of the "Digest::Bcrypt" object, and returns it.
167
168   digest
169           my $digest = $bcrypt->digest;
170
171       Returns the binary digest for the message. The returned string will be
172       23 bytes long.
173
174   hexdigest
175           my $digest = $bcrypt->hexdigest;
176
177       Same as "digest", but will return the digest in hexadecimal form.
178
179       The "length" of the returned string will be 46 and will only contain
180       characters from the ranges '0'..'9' and 'a'..'f'.
181
182   reset
183           $bcrypt->reset;
184
185       Resets the object to the same internal state it was in when it was
186       constructed.
187

SEE ALSO

189       Digest, Crypt::Eksblowfish::Bcrypt, Data::Entropy::Algorithms
190

AUTHOR

192       James Aitken "jaitken@cpan.org"
193

CONTRIBUTORS

195       ·   Chase Whitener "capoeira@cpan.org"
196

198       This software is copyright (c) 2012 by James Aitken.
199
200       This is free software; you can redistribute it and/or modify it under
201       the same terms as the Perl 5 programming language system itself.
202
203
204
205perl v5.30.0                      2019-07-26                 Digest::Bcrypt(3)
Impressum