README
1NAME
2
3 Digest::Bcrypt - Perl interface to the bcrypt digest algorithm
4
5SYNOPSIS
6
7 #!/usr/bin/env perl
8 use strict;
9 use warnings;
10 use utf8;
11 use Digest; # via the Digest module (recommended)
12
13 my $bcrypt = Digest->new('Bcrypt', cost => 12, salt => 'abcdefgh♥stuff');
14 # You can forego the cost and salt in favor of settings strings:
15 my $bcrypt = Digest->new('Bcrypt', settings => '$2a$20$GA.eY03tb02ea0DqbA.eG.');
16
17 # $cost is an integer between 1 and 31
18 $bcrypt->cost(12);
19
20 # $salt must be exactly 16 octets long
21 $bcrypt->salt('abcdefgh♥stuff');
22 # OR, for good, random salts:
23 use Data::Entropy::Algorithms qw(rand_bits);
24 $bcrypt->salt(rand_bits(16*8)); # 16 octets
25
26 # You can forego the cost and salt in favor of settings strings:
27 $bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.');
28
29 # add some strings we want to make a secret of
30 $bcrypt->add('some stuff', 'here and', 'here');
31
32 my $digest = $bcrypt->digest;
33 $digest = $bcrypt->hexdigest;
34 $digest = $bcrypt->b64digest;
35
36 # bcrypt's own non-standard base64 dictionary
37 $digest = $bcrypt->bcrypt_b64digest;
38
39 # Now, let's create a password hash and check it later:
40 use Data::Entropy::Algorithms qw(rand_bits);
41 my $bcrypt = Digest->new('Bcrypt', cost=>20, salt=>rand_bits(16*8));
42 my $settings = $bcrypt->settings(); # save for later checks.
43 my $pass_hash = $bcrypt->add('Some secret password')->digest;
44 # much later, we can check a password against our hash via:
45 my $bcrypt = Digest->new('Bcrypt', settings=>$settings);
46 if ($bcrypt->add($value_from_user)->digest eq $known_pass_hash) {
47 say "Your password matched";
48 }
49 else {
50 say "Try again!";
51 }
52
53NOTICE
54
55 While maintenance for Digest::Bcrypt will continue, there's no reason
56 to use Digest::Bcrypt when Crypt::Eksblowfish::Bcrypt already exists.
57 We suggest that you use Crypt::Eksblowfish::Bcrypt instead.
58
59DESCRIPTION
60
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
67ATTRIBUTES
68
69 Digest::Bcrypt implements the following attributes.
70
71 cost
72
73 $bcrypt = $bcrypt->cost(20); # allows for method chaining
74 my $cost = $bcrypt->cost();
75
76 An integer in the range 1..31, this is required.
77
78 See Crypt::Eksblowfish::Bcrypt for a detailed description of cost in
79 the context of the bcrypt algorithm.
80
81 When called with no arguments, it will return the current cost.
82
83 salt
84
85 $bcrypt = $bcrypt->salt('abcdefgh♥stuff'); # allows for method chaining
86 my $salt = $bcrypt->salt();
87
88 # OR, for good, random salts:
89 use Data::Entropy::Algorithms qw(rand_bits);
90 $bcrypt->salt(rand_bits(16*8)); # 16 octets
91
92 Sets the value to be used as a salt. Bcrypt requires exactly 16 octets
93 of salt.
94
95 It is recommenced that you use a module like Data::Entropy::Algorithms
96 to provide a truly randomized salt.
97
98 When called with no arguments, it will return the current salt.
99
100 settings
101
102 $bcrypt = $bcrypt->settings('$2a$20$GA.eY03tb02ea0DqbA.eG.'); # allows for method chaining
103 my $settings = $bcrypt->settings();
104
105 A settings string can be used to set the "salt" in Digest::Bcrypt and
106 "cost" in Digest::Bcrypt automatically. Setting the settings will
107 override any current values in your cost and salt attributes.
108
109 For details on the settings string requirements, please see
110 Crypt::Eksblowfish::Bcrypt.
111
112 When called with no arguments, it will return the current settings
113 string.
114
115METHODS
116
117 Digest::Bcrypt inherits all methods from Digest::base and
118 implements/overrides the following methods as well.
119
120 new
121
122 my $bcrypt = Digest->new('Bcrypt', %params);
123 my $bcrypt = Digest::Bcrypt->new(%params);
124 my $bcrypt = Digest->new('Bcrypt', \%params);
125 my $bcrypt = Digest::Bcrypt->new(\%params);
126
127 Creates a new Digest::Bcrypt object. It is recommended that you use the
128 Digest module in the first example rather than using Digest::Bcrypt
129 directly.
130
131 Any of the "ATTRIBUTES" in Digest::Bcrypt above can be passed in as a
132 parameter.
133
134 add
135
136 $bcrypt->add("a"); $bcrypt->add("b"); $bcrypt->add("c");
137 $bcrypt->add("a")->add("b")->add("c");
138 $bcrypt->add("a", "b", "c");
139 $bcrypt->add("abc");
140
141 Adds data to the message we are calculating the digest for. All the
142 above examples have the same effect.
143
144 b64digest
145
146 my $digest = $bcrypt->b64digest;
147
148 Same as "digest", but will return the digest base64 encoded.
149
150 The length of the returned string will be 31 and will only contain
151 characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '/'
152
153 The base64 encoded string returned is not padded to be a multiple of 4
154 bytes long.
155
156 bcrypt_b64digest
157
158 my $digest = $bcrypt->bcrypt_b64digest;
159
160 Same as "digest", but will return the digest base64 encoded using the
161 alphabet that is commonly used with bcrypt.
162
163 The length of the returned string will be 31 and will only contain
164 characters from the ranges '0'..'9', 'A'..'Z', 'a'..'z', '+', and '.'
165
166 The base64 encoded string returned is not padded to be a multiple of 4
167 bytes long.
168
169 Note: This is bcrypt's own non-standard base64 alphabet, It is not
170 compatible with the standard MIME base64 encoding.
171
172 clone
173
174 my $clone = $bcrypt->clone;
175
176 Creates a clone of the Digest::Bcrypt object, and returns it.
177
178 digest
179
180 my $digest = $bcrypt->digest;
181
182 Returns the binary digest for the message. The returned string will be
183 23 bytes long.
184
185 hexdigest
186
187 my $digest = $bcrypt->hexdigest;
188
189 Same as "digest", but will return the digest in hexadecimal form.
190
191 The length of the returned string will be 46 and will only contain
192 characters from the ranges '0'..'9' and 'a'..'f'.
193
194 reset
195
196 $bcrypt->reset;
197
198 Resets the object to the same internal state it was in when it was
199 constructed.
200
201SEE ALSO
202
203 Digest, Crypt::Eksblowfish::Bcrypt, Data::Entropy::Algorithms
204
205AUTHOR
206
207 James Aitken jaitken@cpan.org
208
209CONTRIBUTORS
210
211 * Chase Whitener capoeira@cpan.org
212
213COPYRIGHT AND LICENSE
214
215 This software is copyright (c) 2012 by James Aitken.
216
217 This is free software; you can redistribute it and/or modify it under
218 the same terms as the Perl 5 programming language system itself.
219
220