line |
stmt |
bran |
cond |
sub |
pod |
time |
code |
1
|
|
|
|
|
|
|
package Dancer::Plugin::Passphrase; |
2
|
|
|
|
|
|
|
|
3
|
|
|
|
|
|
|
# ABSTRACT: Passphrases and Passwords as objects for Dancer |
4
|
|
|
|
|
|
|
|
5
|
|
|
|
|
|
|
=head1 NAME |
6
|
|
|
|
|
|
|
|
7
|
|
|
|
|
|
|
Dancer::Plugin::Passphrase - Passphrases and Passwords as objects for Dancer |
8
|
|
|
|
|
|
|
|
9
|
|
|
|
|
|
|
=head1 SYNOPSIS |
10
|
|
|
|
|
|
|
|
11
|
|
|
|
|
|
|
This plugin manages the hashing of passwords for Dancer apps, allowing |
12
|
|
|
|
|
|
|
developers to follow cryptography best practices without having to |
13
|
|
|
|
|
|
|
become a cryptography expert. |
14
|
|
|
|
|
|
|
|
15
|
|
|
|
|
|
|
It uses the bcrypt algorithm as the default, while also supporting any |
16
|
|
|
|
|
|
|
hashing function provided by L |
17
|
|
|
|
|
|
|
|
18
|
|
|
|
|
|
|
=head1 USAGE |
19
|
|
|
|
|
|
|
|
20
|
|
|
|
|
|
|
package MyWebService; |
21
|
|
|
|
|
|
|
use Dancer ':syntax'; |
22
|
|
|
|
|
|
|
use Dancer::Plugin::Passphrase; |
23
|
|
|
|
|
|
|
|
24
|
|
|
|
|
|
|
post '/login' => sub { |
25
|
|
|
|
|
|
|
my $phrase = passphrase( param('my password') )->generate; |
26
|
|
|
|
|
|
|
|
27
|
|
|
|
|
|
|
# $phrase is now an object that contains RFC 2307 representation |
28
|
|
|
|
|
|
|
# of the hashed passphrase, along with the salt, and other metadata |
29
|
|
|
|
|
|
|
|
30
|
|
|
|
|
|
|
# You should store $phrase->rfc2307() for use later |
31
|
|
|
|
|
|
|
}; |
32
|
|
|
|
|
|
|
|
33
|
|
|
|
|
|
|
get '/protected' => sub { |
34
|
|
|
|
|
|
|
# Retrieve $stored_rfc_2307_string, like we created above. |
35
|
|
|
|
|
|
|
# IT MUST be a valid RFC 2307 string |
36
|
|
|
|
|
|
|
|
37
|
|
|
|
|
|
|
if ( passphrase( param('my password') )->matches( $stored_rfc_2307 ) ) { |
38
|
|
|
|
|
|
|
# Passphrase matches! |
39
|
|
|
|
|
|
|
} |
40
|
|
|
|
|
|
|
}; |
41
|
|
|
|
|
|
|
|
42
|
|
|
|
|
|
|
get '/generate_new_password' => sub { |
43
|
|
|
|
|
|
|
return passphrase->generate_random; |
44
|
|
|
|
|
|
|
}; |
45
|
|
|
|
|
|
|
|
46
|
|
|
|
|
|
|
=cut |
47
|
|
|
|
|
|
|
|
48
|
1
|
|
|
1
|
|
888
|
use strict; |
|
1
|
|
|
|
|
2
|
|
|
1
|
|
|
|
|
41
|
|
49
|
|
|
|
|
|
|
|
50
|
1
|
|
|
1
|
|
443
|
use Dancer::Plugin; |
|
0
|
|
|
|
|
|
|
|
0
|
|
|
|
|
|
|
51
|
|
|
|
|
|
|
|
52
|
|
|
|
|
|
|
use Carp qw(carp croak); |
53
|
|
|
|
|
|
|
use Data::Entropy::Algorithms qw(rand_bits rand_int); |
54
|
|
|
|
|
|
|
use Digest; |
55
|
|
|
|
|
|
|
use MIME::Base64 qw(decode_base64 encode_base64); |
56
|
|
|
|
|
|
|
use Scalar::Util qw(blessed); |
57
|
|
|
|
|
|
|
|
58
|
|
|
|
|
|
|
our $VERSION = '2.0.1'; |
59
|
|
|
|
|
|
|
|
60
|
|
|
|
|
|
|
# Auto stringifies and returns the RFC 2307 representation |
61
|
|
|
|
|
|
|
# of the object unless we are calling a method on it |
62
|
|
|
|
|
|
|
use overload ( |
63
|
|
|
|
|
|
|
'""' => sub { |
64
|
|
|
|
|
|
|
if (blessed($_[0]) && $_[0]->isa('Dancer::Plugin::Passphrase')) { |
65
|
|
|
|
|
|
|
$_[0]->rfc2307(); |
66
|
|
|
|
|
|
|
} |
67
|
|
|
|
|
|
|
}, |
68
|
|
|
|
|
|
|
fallback => 1, |
69
|
|
|
|
|
|
|
); |
70
|
|
|
|
|
|
|
|
71
|
|
|
|
|
|
|
register passphrase => \&passphrase; |
72
|
|
|
|
|
|
|
|
73
|
|
|
|
|
|
|
|
74
|
|
|
|
|
|
|
=head1 KEYWORDS |
75
|
|
|
|
|
|
|
|
76
|
|
|
|
|
|
|
=head2 passphrase |
77
|
|
|
|
|
|
|
|
78
|
|
|
|
|
|
|
Given a plaintext password, it returns a Dancer::Plugin::Passphrase |
79
|
|
|
|
|
|
|
object that you can generate a new hash from, or match against a stored hash. |
80
|
|
|
|
|
|
|
|
81
|
|
|
|
|
|
|
=cut |
82
|
|
|
|
|
|
|
|
83
|
|
|
|
|
|
|
sub passphrase { |
84
|
|
|
|
|
|
|
# Dancer 2 keywords receive a reference to the DSL object as a first param. |
85
|
|
|
|
|
|
|
# We don't need it, so get rid of it, and just get the plaintext |
86
|
|
|
|
|
|
|
shift if blessed($_[0]) && $_[0]->isa('Dancer::Core::DSL'); |
87
|
|
|
|
|
|
|
|
88
|
|
|
|
|
|
|
my $plaintext = $_[0]; |
89
|
|
|
|
|
|
|
|
90
|
|
|
|
|
|
|
return bless { |
91
|
|
|
|
|
|
|
plaintext => $plaintext |
92
|
|
|
|
|
|
|
}, 'Dancer::Plugin::Passphrase'; |
93
|
|
|
|
|
|
|
} |
94
|
|
|
|
|
|
|
|
95
|
|
|
|
|
|
|
|
96
|
|
|
|
|
|
|
|
97
|
|
|
|
|
|
|
=head1 MAIN METHODS |
98
|
|
|
|
|
|
|
|
99
|
|
|
|
|
|
|
=head2 generate |
100
|
|
|
|
|
|
|
|
101
|
|
|
|
|
|
|
Generates an RFC 2307 representation of the hashed passphrase |
102
|
|
|
|
|
|
|
that is suitable for storage in a database. |
103
|
|
|
|
|
|
|
|
104
|
|
|
|
|
|
|
my $pass = passphrase('my passphrase')->generate; |
105
|
|
|
|
|
|
|
|
106
|
|
|
|
|
|
|
You should store C<$phrase->rfc_2307()> in your database. For convenience |
107
|
|
|
|
|
|
|
the object will automagically return the RFC 2307 representation when no |
108
|
|
|
|
|
|
|
method is called on it. |
109
|
|
|
|
|
|
|
|
110
|
|
|
|
|
|
|
Accepts a hashref of options to specify what kind of hash should be |
111
|
|
|
|
|
|
|
generated. All options settable in the config file are valid. |
112
|
|
|
|
|
|
|
|
113
|
|
|
|
|
|
|
If you specify only the algorithm, the default settings for that algorithm will be used. |
114
|
|
|
|
|
|
|
|
115
|
|
|
|
|
|
|
A cryptographically random salt is used if salt is not defined. |
116
|
|
|
|
|
|
|
Only if you specify the empty string will an empty salt be used |
117
|
|
|
|
|
|
|
This is not recommended, and should only be used to upgrade old insecure hashes |
118
|
|
|
|
|
|
|
|
119
|
|
|
|
|
|
|
my $phrase = passphrase('my password')->generate({ |
120
|
|
|
|
|
|
|
algorithm => '', # What algorithm is used to generate the hash |
121
|
|
|
|
|
|
|
cost => '', # Cost / Work Factor if using bcrypt |
122
|
|
|
|
|
|
|
salt => '', # Manually specify salt if using a salted digest |
123
|
|
|
|
|
|
|
}); |
124
|
|
|
|
|
|
|
|
125
|
|
|
|
|
|
|
=cut |
126
|
|
|
|
|
|
|
|
127
|
|
|
|
|
|
|
sub generate { |
128
|
|
|
|
|
|
|
my ($self, $options) = @_; |
129
|
|
|
|
|
|
|
|
130
|
|
|
|
|
|
|
$self->_get_settings($options); |
131
|
|
|
|
|
|
|
$self->_calculate_hash; |
132
|
|
|
|
|
|
|
|
133
|
|
|
|
|
|
|
return $self; |
134
|
|
|
|
|
|
|
} |
135
|
|
|
|
|
|
|
|
136
|
|
|
|
|
|
|
sub generate_hash { |
137
|
|
|
|
|
|
|
carp "generate_hash method is deprecated"; |
138
|
|
|
|
|
|
|
return shift->generate(); |
139
|
|
|
|
|
|
|
} |
140
|
|
|
|
|
|
|
|
141
|
|
|
|
|
|
|
|
142
|
|
|
|
|
|
|
=head2 matches |
143
|
|
|
|
|
|
|
|
144
|
|
|
|
|
|
|
Matches a plaintext password against a stored hash. |
145
|
|
|
|
|
|
|
Returns 1 if the hash of the password matches the stored hash. |
146
|
|
|
|
|
|
|
Returns undef if they don't match or if there was an error |
147
|
|
|
|
|
|
|
Fail-Secure, rather than Fail-Safe. |
148
|
|
|
|
|
|
|
|
149
|
|
|
|
|
|
|
passphrase('my password')->matches($stored_rfc_2307_string); |
150
|
|
|
|
|
|
|
|
151
|
|
|
|
|
|
|
$stored_rfc_2307_string B be a valid RFC 2307 string, |
152
|
|
|
|
|
|
|
as created by L |
153
|
|
|
|
|
|
|
|
154
|
|
|
|
|
|
|
An RFC 2307 string is made up of a scheme identifier, followed by a |
155
|
|
|
|
|
|
|
base64 encoded string. The base64 encoded string should contain |
156
|
|
|
|
|
|
|
the password hash and the salt concatenated together - in that order. |
157
|
|
|
|
|
|
|
|
158
|
|
|
|
|
|
|
'{'.$scheme.'}'.encode_base64($hash . $salt, ''); |
159
|
|
|
|
|
|
|
|
160
|
|
|
|
|
|
|
Where C<$scheme> can be any of the following and their unsalted variants, |
161
|
|
|
|
|
|
|
which have the leading S removed. CRYPT will be Bcrypt. |
162
|
|
|
|
|
|
|
|
163
|
|
|
|
|
|
|
SMD5 SSHA SSHA224 SSHA256 SSHA384 SSHA512 CRYPT |
164
|
|
|
|
|
|
|
|
165
|
|
|
|
|
|
|
A complete RFC2307 string looks like this: |
166
|
|
|
|
|
|
|
|
167
|
|
|
|
|
|
|
{SSHA}K3LAbIjRL5CpLzOlm3/HzS3qt/hUaGVTYWx0 |
168
|
|
|
|
|
|
|
|
169
|
|
|
|
|
|
|
This is the format created by L |
170
|
|
|
|
|
|
|
|
171
|
|
|
|
|
|
|
=cut |
172
|
|
|
|
|
|
|
|
173
|
|
|
|
|
|
|
sub matches { |
174
|
|
|
|
|
|
|
my ($self, $stored_hash) = @_; |
175
|
|
|
|
|
|
|
|
176
|
|
|
|
|
|
|
# Force auto stringification in case we were passed an object. |
177
|
|
|
|
|
|
|
($stored_hash) = ($stored_hash =~ m/(.*)/s); |
178
|
|
|
|
|
|
|
|
179
|
|
|
|
|
|
|
my $new_hash = $self->_extract_settings($stored_hash)->_calculate_hash->rfc2307; |
180
|
|
|
|
|
|
|
|
181
|
|
|
|
|
|
|
return ($new_hash eq $stored_hash) ? 1 : undef; |
182
|
|
|
|
|
|
|
} |
183
|
|
|
|
|
|
|
|
184
|
|
|
|
|
|
|
|
185
|
|
|
|
|
|
|
|
186
|
|
|
|
|
|
|
=head2 generate_random |
187
|
|
|
|
|
|
|
|
188
|
|
|
|
|
|
|
Generates and returns any number of cryptographically random |
189
|
|
|
|
|
|
|
characters from the url-safe base64 charater set. |
190
|
|
|
|
|
|
|
|
191
|
|
|
|
|
|
|
my $rand_pass = passphrase->generate_random; |
192
|
|
|
|
|
|
|
|
193
|
|
|
|
|
|
|
The passwords generated are suitable for use as |
194
|
|
|
|
|
|
|
temporary passwords or one-time authentication tokens. |
195
|
|
|
|
|
|
|
|
196
|
|
|
|
|
|
|
You can configure the length and the character set |
197
|
|
|
|
|
|
|
used by passing a hashref of options. |
198
|
|
|
|
|
|
|
|
199
|
|
|
|
|
|
|
my $rand_pass = passphrase->generate_random({ |
200
|
|
|
|
|
|
|
length => 32, |
201
|
|
|
|
|
|
|
charset => ['a'..'z', 'A'..'Z'], |
202
|
|
|
|
|
|
|
}); |
203
|
|
|
|
|
|
|
|
204
|
|
|
|
|
|
|
=cut |
205
|
|
|
|
|
|
|
|
206
|
|
|
|
|
|
|
sub generate_random { |
207
|
|
|
|
|
|
|
my ($self, $options) = @_; |
208
|
|
|
|
|
|
|
|
209
|
|
|
|
|
|
|
# Default is 16 URL-safe base64 chars. Supported everywhere and a reasonable length |
210
|
|
|
|
|
|
|
my $length = $options->{length} || 16; |
211
|
|
|
|
|
|
|
my $charset = $options->{charset} || ['a'..'z', 'A'..'Z', '0'..'9', '-', '_']; |
212
|
|
|
|
|
|
|
|
213
|
|
|
|
|
|
|
return join '', map { @$charset[rand_int scalar @$charset] } 1..$length; |
214
|
|
|
|
|
|
|
} |
215
|
|
|
|
|
|
|
|
216
|
|
|
|
|
|
|
|
217
|
|
|
|
|
|
|
|
218
|
|
|
|
|
|
|
=head1 ADDITIONAL METHODS |
219
|
|
|
|
|
|
|
|
220
|
|
|
|
|
|
|
The methods are only applicable once you have called C |
221
|
|
|
|
|
|
|
|
222
|
|
|
|
|
|
|
passphrase( 'my password' )->generate->rfc2307; # CORRECT |
223
|
|
|
|
|
|
|
|
224
|
|
|
|
|
|
|
passphrase( 'my password' )->rfc2307; # INCORRECT, Returns undef |
225
|
|
|
|
|
|
|
|
226
|
|
|
|
|
|
|
|
227
|
|
|
|
|
|
|
=head2 rfc2307 |
228
|
|
|
|
|
|
|
|
229
|
|
|
|
|
|
|
Returns the rfc2307 representation from a C object. |
230
|
|
|
|
|
|
|
|
231
|
|
|
|
|
|
|
passphrase('my password')->generate->rfc2307; |
232
|
|
|
|
|
|
|
|
233
|
|
|
|
|
|
|
=cut |
234
|
|
|
|
|
|
|
|
235
|
|
|
|
|
|
|
sub rfc2307 { |
236
|
|
|
|
|
|
|
return shift->{rfc2307} || undef; |
237
|
|
|
|
|
|
|
} |
238
|
|
|
|
|
|
|
|
239
|
|
|
|
|
|
|
sub as_rfc2307 { |
240
|
|
|
|
|
|
|
carp "as_rfc2307 method is deprecated"; |
241
|
|
|
|
|
|
|
return shift->rfc2307(); |
242
|
|
|
|
|
|
|
} |
243
|
|
|
|
|
|
|
|
244
|
|
|
|
|
|
|
|
245
|
|
|
|
|
|
|
|
246
|
|
|
|
|
|
|
=head2 scheme |
247
|
|
|
|
|
|
|
|
248
|
|
|
|
|
|
|
Returns the scheme name from a C object. |
249
|
|
|
|
|
|
|
|
250
|
|
|
|
|
|
|
This is the scheme name as used in the RFC 2307 representation |
251
|
|
|
|
|
|
|
|
252
|
|
|
|
|
|
|
passphrase('my password')->generate->scheme; |
253
|
|
|
|
|
|
|
|
254
|
|
|
|
|
|
|
The scheme name can be any of the following, and will always be capitalized |
255
|
|
|
|
|
|
|
|
256
|
|
|
|
|
|
|
SMD5 SSHA SSHA224 SSHA256 SSHA384 SSHA512 CRYPT |
257
|
|
|
|
|
|
|
MD5 SHA SHA224 SHA256 SHA384 SHA512 |
258
|
|
|
|
|
|
|
|
259
|
|
|
|
|
|
|
=cut |
260
|
|
|
|
|
|
|
|
261
|
|
|
|
|
|
|
sub scheme { |
262
|
|
|
|
|
|
|
return shift->{scheme} || undef; |
263
|
|
|
|
|
|
|
} |
264
|
|
|
|
|
|
|
|
265
|
|
|
|
|
|
|
|
266
|
|
|
|
|
|
|
=head2 algorithm |
267
|
|
|
|
|
|
|
|
268
|
|
|
|
|
|
|
Returns the algorithm name from a C object. |
269
|
|
|
|
|
|
|
|
270
|
|
|
|
|
|
|
The algorithm name can be anything that is accepted by Cnew($alg)> |
271
|
|
|
|
|
|
|
This includes any modules in the C Namespace |
272
|
|
|
|
|
|
|
|
273
|
|
|
|
|
|
|
passphrase('my password')->generate->algorithm; |
274
|
|
|
|
|
|
|
|
275
|
|
|
|
|
|
|
=cut |
276
|
|
|
|
|
|
|
|
277
|
|
|
|
|
|
|
sub algorithm { |
278
|
|
|
|
|
|
|
return shift->{algorithm} || undef; |
279
|
|
|
|
|
|
|
} |
280
|
|
|
|
|
|
|
|
281
|
|
|
|
|
|
|
|
282
|
|
|
|
|
|
|
=head2 cost |
283
|
|
|
|
|
|
|
|
284
|
|
|
|
|
|
|
Returns the bcrypt cost from a C object. |
285
|
|
|
|
|
|
|
Only works when using the bcrypt algorithm, returns undef for other algorithms |
286
|
|
|
|
|
|
|
|
287
|
|
|
|
|
|
|
passphrase('my password')->generate->cost; |
288
|
|
|
|
|
|
|
|
289
|
|
|
|
|
|
|
=cut |
290
|
|
|
|
|
|
|
|
291
|
|
|
|
|
|
|
sub cost { |
292
|
|
|
|
|
|
|
return shift->{cost} || undef; |
293
|
|
|
|
|
|
|
} |
294
|
|
|
|
|
|
|
|
295
|
|
|
|
|
|
|
|
296
|
|
|
|
|
|
|
=head2 salt_raw |
297
|
|
|
|
|
|
|
|
298
|
|
|
|
|
|
|
Returns the raw salt from a C object. |
299
|
|
|
|
|
|
|
|
300
|
|
|
|
|
|
|
passphrase('my password')->generate->salt_raw; |
301
|
|
|
|
|
|
|
|
302
|
|
|
|
|
|
|
Can be defined, but false - The empty string is technically a valid salt. |
303
|
|
|
|
|
|
|
|
304
|
|
|
|
|
|
|
Returns C if there is no salt. |
305
|
|
|
|
|
|
|
|
306
|
|
|
|
|
|
|
=cut |
307
|
|
|
|
|
|
|
|
308
|
|
|
|
|
|
|
sub salt_raw { |
309
|
|
|
|
|
|
|
return shift->{salt} // undef; |
310
|
|
|
|
|
|
|
} |
311
|
|
|
|
|
|
|
|
312
|
|
|
|
|
|
|
sub raw_salt { |
313
|
|
|
|
|
|
|
carp "raw_salt method is deprecated"; |
314
|
|
|
|
|
|
|
return shift->salt_raw(); |
315
|
|
|
|
|
|
|
} |
316
|
|
|
|
|
|
|
|
317
|
|
|
|
|
|
|
=head2 hash_raw |
318
|
|
|
|
|
|
|
|
319
|
|
|
|
|
|
|
Returns the raw hash from a C object. |
320
|
|
|
|
|
|
|
|
321
|
|
|
|
|
|
|
passphrase('my password')->generate->hash_raw; |
322
|
|
|
|
|
|
|
|
323
|
|
|
|
|
|
|
=cut |
324
|
|
|
|
|
|
|
|
325
|
|
|
|
|
|
|
sub hash_raw { |
326
|
|
|
|
|
|
|
return shift->{hash} || undef; |
327
|
|
|
|
|
|
|
} |
328
|
|
|
|
|
|
|
|
329
|
|
|
|
|
|
|
sub raw_hash { |
330
|
|
|
|
|
|
|
carp "raw_hash method is deprecated"; |
331
|
|
|
|
|
|
|
return shift->hash_raw(); |
332
|
|
|
|
|
|
|
} |
333
|
|
|
|
|
|
|
|
334
|
|
|
|
|
|
|
|
335
|
|
|
|
|
|
|
=head2 salt_hex |
336
|
|
|
|
|
|
|
|
337
|
|
|
|
|
|
|
Returns the hex-encoded salt from a C object. |
338
|
|
|
|
|
|
|
|
339
|
|
|
|
|
|
|
Can be defined, but false - The empty string is technically a valid salt. |
340
|
|
|
|
|
|
|
Returns C if there is no salt. |
341
|
|
|
|
|
|
|
|
342
|
|
|
|
|
|
|
passphrase('my password')->generate->salt_hex; |
343
|
|
|
|
|
|
|
|
344
|
|
|
|
|
|
|
=cut |
345
|
|
|
|
|
|
|
|
346
|
|
|
|
|
|
|
sub salt_hex { |
347
|
|
|
|
|
|
|
return unpack("H*", shift->{salt}) // undef; |
348
|
|
|
|
|
|
|
} |
349
|
|
|
|
|
|
|
|
350
|
|
|
|
|
|
|
|
351
|
|
|
|
|
|
|
=head2 hash_hex |
352
|
|
|
|
|
|
|
|
353
|
|
|
|
|
|
|
Returns the hex-encoded hash from a C object. |
354
|
|
|
|
|
|
|
|
355
|
|
|
|
|
|
|
passphrase('my password')->generate->hash_hex; |
356
|
|
|
|
|
|
|
|
357
|
|
|
|
|
|
|
=cut |
358
|
|
|
|
|
|
|
|
359
|
|
|
|
|
|
|
sub hash_hex { |
360
|
|
|
|
|
|
|
return unpack("H*", shift->{hash}) || undef; |
361
|
|
|
|
|
|
|
} |
362
|
|
|
|
|
|
|
|
363
|
|
|
|
|
|
|
|
364
|
|
|
|
|
|
|
=head2 salt_base64 |
365
|
|
|
|
|
|
|
|
366
|
|
|
|
|
|
|
Returns the base64 encoded salt from a C object. |
367
|
|
|
|
|
|
|
|
368
|
|
|
|
|
|
|
Can be defined, but false - The empty string is technically a valid salt. |
369
|
|
|
|
|
|
|
Returns C if there is no salt. |
370
|
|
|
|
|
|
|
|
371
|
|
|
|
|
|
|
passphrase('my password')->generate->salt_base64; |
372
|
|
|
|
|
|
|
|
373
|
|
|
|
|
|
|
=cut |
374
|
|
|
|
|
|
|
|
375
|
|
|
|
|
|
|
sub salt_base64 { |
376
|
|
|
|
|
|
|
return encode_base64(shift->{salt}, '') // undef; |
377
|
|
|
|
|
|
|
} |
378
|
|
|
|
|
|
|
|
379
|
|
|
|
|
|
|
|
380
|
|
|
|
|
|
|
=head2 hash_base64 |
381
|
|
|
|
|
|
|
|
382
|
|
|
|
|
|
|
Returns the base64 encoded hash from a C object. |
383
|
|
|
|
|
|
|
|
384
|
|
|
|
|
|
|
passphrase('my password')->generate->hash_base64; |
385
|
|
|
|
|
|
|
|
386
|
|
|
|
|
|
|
=cut |
387
|
|
|
|
|
|
|
|
388
|
|
|
|
|
|
|
sub hash_base64 { |
389
|
|
|
|
|
|
|
return encode_base64(shift->{hash}, '') || undef; |
390
|
|
|
|
|
|
|
} |
391
|
|
|
|
|
|
|
|
392
|
|
|
|
|
|
|
=head2 plaintext |
393
|
|
|
|
|
|
|
|
394
|
|
|
|
|
|
|
Returns the plaintext password as originally supplied to the L keyword. |
395
|
|
|
|
|
|
|
|
396
|
|
|
|
|
|
|
passphrase('my password')->generate->plaintext; |
397
|
|
|
|
|
|
|
|
398
|
|
|
|
|
|
|
=cut |
399
|
|
|
|
|
|
|
|
400
|
|
|
|
|
|
|
sub plaintext { |
401
|
|
|
|
|
|
|
return shift->{plaintext} || undef; |
402
|
|
|
|
|
|
|
} |
403
|
|
|
|
|
|
|
|
404
|
|
|
|
|
|
|
|
405
|
|
|
|
|
|
|
|
406
|
|
|
|
|
|
|
# Actual generation of the hash, using the provided settings |
407
|
|
|
|
|
|
|
sub _calculate_hash { |
408
|
|
|
|
|
|
|
my $self = shift; |
409
|
|
|
|
|
|
|
|
410
|
|
|
|
|
|
|
my $hasher = Digest->new( $self->algorithm ); |
411
|
|
|
|
|
|
|
|
412
|
|
|
|
|
|
|
if ($self->algorithm eq 'Bcrypt') { |
413
|
|
|
|
|
|
|
$hasher->add($self->{plaintext}); |
414
|
|
|
|
|
|
|
$hasher->salt($self->salt_raw); |
415
|
|
|
|
|
|
|
$hasher->cost($self->cost); |
416
|
|
|
|
|
|
|
|
417
|
|
|
|
|
|
|
$self->{hash} = $hasher->digest; |
418
|
|
|
|
|
|
|
$self->{rfc2307} |
419
|
|
|
|
|
|
|
= '{CRYPT}$' |
420
|
|
|
|
|
|
|
. $self->{type} . '$' |
421
|
|
|
|
|
|
|
. $self->cost . '$' |
422
|
|
|
|
|
|
|
. _en_bcrypt_base64($self->salt_raw) |
423
|
|
|
|
|
|
|
. _en_bcrypt_base64($self->hash_raw); |
424
|
|
|
|
|
|
|
} else { |
425
|
|
|
|
|
|
|
$hasher->add($self->{plaintext}); |
426
|
|
|
|
|
|
|
$hasher->add($self->{salt}); |
427
|
|
|
|
|
|
|
|
428
|
|
|
|
|
|
|
$self->{hash} = $hasher->digest; |
429
|
|
|
|
|
|
|
$self->{rfc2307} |
430
|
|
|
|
|
|
|
= '{' . $self->{scheme} . '}' |
431
|
|
|
|
|
|
|
. encode_base64($self->hash_raw . $self->salt_raw, ''); |
432
|
|
|
|
|
|
|
} |
433
|
|
|
|
|
|
|
|
434
|
|
|
|
|
|
|
return $self; |
435
|
|
|
|
|
|
|
} |
436
|
|
|
|
|
|
|
|
437
|
|
|
|
|
|
|
|
438
|
|
|
|
|
|
|
# Extracts the settings from an RFC 2307 string |
439
|
|
|
|
|
|
|
sub _extract_settings { |
440
|
|
|
|
|
|
|
my ($self, $rfc2307_string) = @_; |
441
|
|
|
|
|
|
|
|
442
|
|
|
|
|
|
|
my ($scheme, $settings) = ($rfc2307_string =~ m/^{(\w+)}(.*)/s); |
443
|
|
|
|
|
|
|
|
444
|
|
|
|
|
|
|
unless ($scheme && $settings) { |
445
|
|
|
|
|
|
|
croak "An RFC 2307 compliant string must be passed to matches()"; |
446
|
|
|
|
|
|
|
} |
447
|
|
|
|
|
|
|
|
448
|
|
|
|
|
|
|
if ($scheme eq 'CRYPT'){ |
449
|
|
|
|
|
|
|
if ($settings =~ m/^\$2(?:a|x|y)\$/) { |
450
|
|
|
|
|
|
|
$scheme = 'Bcrypt'; |
451
|
|
|
|
|
|
|
$settings =~ m{\A\$(2a|2x|2y)\$([0-9]{2})\$([./A-Za-z0-9]{22})}x; |
452
|
|
|
|
|
|
|
|
453
|
|
|
|
|
|
|
($self->{type}, $self->{cost}, $self->{salt}) = ($1, $2, _de_bcrypt_base64($3)); |
454
|
|
|
|
|
|
|
} else { |
455
|
|
|
|
|
|
|
croak "Unknown CRYPT format: $_"; |
456
|
|
|
|
|
|
|
} |
457
|
|
|
|
|
|
|
} |
458
|
|
|
|
|
|
|
|
459
|
|
|
|
|
|
|
my $scheme_meta = { |
460
|
|
|
|
|
|
|
'MD5' => { algorithm => 'MD5', octets => 128 / 8 }, |
461
|
|
|
|
|
|
|
'SMD5' => { algorithm => 'MD5', octets => 128 / 8 }, |
462
|
|
|
|
|
|
|
'SHA' => { algorithm => 'SHA-1', octets => 160 / 8 }, |
463
|
|
|
|
|
|
|
'SSHA' => { algorithm => 'SHA-1', octets => 160 / 8 }, |
464
|
|
|
|
|
|
|
'SHA224' => { algorithm => 'SHA-224', octets => 224 / 8 }, |
465
|
|
|
|
|
|
|
'SSHA224' => { algorithm => 'SHA-224', octets => 224 / 8 }, |
466
|
|
|
|
|
|
|
'SHA256' => { algorithm => 'SHA-256', octets => 256 / 8 }, |
467
|
|
|
|
|
|
|
'SSHA256' => { algorithm => 'SHA-256', octets => 256 / 8 }, |
468
|
|
|
|
|
|
|
'SHA384' => { algorithm => 'SHA-384', octets => 384 / 8 }, |
469
|
|
|
|
|
|
|
'SSHA384' => { algorithm => 'SHA-384', octets => 384 / 8 }, |
470
|
|
|
|
|
|
|
'SHA512' => { algorithm => 'SHA-512', octets => 512 / 8 }, |
471
|
|
|
|
|
|
|
'SSHA512' => { algorithm => 'SHA-512', octets => 512 / 8 }, |
472
|
|
|
|
|
|
|
'Bcrypt' => { algorithm => 'Bcrypt', octets => 128 / 8 }, |
473
|
|
|
|
|
|
|
}; |
474
|
|
|
|
|
|
|
|
475
|
|
|
|
|
|
|
$self->{scheme} = $scheme; |
476
|
|
|
|
|
|
|
$self->{algorithm} = $scheme_meta->{$scheme}->{algorithm}; |
477
|
|
|
|
|
|
|
|
478
|
|
|
|
|
|
|
if (!defined $self->{salt}) { |
479
|
|
|
|
|
|
|
$self->{salt} = substr(decode_base64($settings), $scheme_meta->{$scheme}->{octets}); |
480
|
|
|
|
|
|
|
} |
481
|
|
|
|
|
|
|
|
482
|
|
|
|
|
|
|
return $self; |
483
|
|
|
|
|
|
|
} |
484
|
|
|
|
|
|
|
|
485
|
|
|
|
|
|
|
|
486
|
|
|
|
|
|
|
# Gets the settings from config.yml, and merges them with any custom |
487
|
|
|
|
|
|
|
# settings given to the constructor |
488
|
|
|
|
|
|
|
sub _get_settings { |
489
|
|
|
|
|
|
|
my ($self, $options) = @_; |
490
|
|
|
|
|
|
|
|
491
|
|
|
|
|
|
|
$self->{algorithm} = $options->{algorithm} || |
492
|
|
|
|
|
|
|
plugin_setting->{algorithm} || |
493
|
|
|
|
|
|
|
'Bcrypt'; |
494
|
|
|
|
|
|
|
|
495
|
|
|
|
|
|
|
my $plugin_setting = plugin_setting->{$self->algorithm}; |
496
|
|
|
|
|
|
|
|
497
|
|
|
|
|
|
|
# Specify empty string to get an unsalted hash |
498
|
|
|
|
|
|
|
# Leaving it undefs results in 128 random bits being used as salt |
499
|
|
|
|
|
|
|
# bcrypt requires this amount, and is reasonable for other algorithms |
500
|
|
|
|
|
|
|
$self->{salt} = $options->{salt} // |
501
|
|
|
|
|
|
|
$plugin_setting->{salt} // |
502
|
|
|
|
|
|
|
rand_bits(128); |
503
|
|
|
|
|
|
|
|
504
|
|
|
|
|
|
|
# RFC 2307 scheme is based on the algorithm, with a prefixed 'S' for salted |
505
|
|
|
|
|
|
|
$self->{scheme} = join '', $self->algorithm =~ /[\w]+/g; |
506
|
|
|
|
|
|
|
$self->{scheme} = 'S'.$self->{scheme} if $self->{salt}; |
507
|
|
|
|
|
|
|
|
508
|
|
|
|
|
|
|
if ($self->{scheme} eq 'SHA1') { |
509
|
|
|
|
|
|
|
$self->{scheme} = 'SHA'; |
510
|
|
|
|
|
|
|
} elsif ($self->{scheme} eq 'SSHA1') { |
511
|
|
|
|
|
|
|
$self->{scheme} = 'SSHA'; |
512
|
|
|
|
|
|
|
} |
513
|
|
|
|
|
|
|
|
514
|
|
|
|
|
|
|
# Bcrypt requires a cost parameter |
515
|
|
|
|
|
|
|
if ($self->algorithm eq 'Bcrypt') { |
516
|
|
|
|
|
|
|
$self->{scheme} = 'CRYPT'; |
517
|
|
|
|
|
|
|
$self->{type} = '2a'; |
518
|
|
|
|
|
|
|
$self->{cost} = $options->{cost} || |
519
|
|
|
|
|
|
|
$plugin_setting->{cost} || |
520
|
|
|
|
|
|
|
4; |
521
|
|
|
|
|
|
|
|
522
|
|
|
|
|
|
|
$self->{cost} = 31 if $self->cost > 31; |
523
|
|
|
|
|
|
|
$self->{cost} = sprintf("%02d", $self->cost); |
524
|
|
|
|
|
|
|
} |
525
|
|
|
|
|
|
|
|
526
|
|
|
|
|
|
|
return $self; |
527
|
|
|
|
|
|
|
} |
528
|
|
|
|
|
|
|
|
529
|
|
|
|
|
|
|
|
530
|
|
|
|
|
|
|
# From Crypt::Eksblowfish::Bcrypt. |
531
|
|
|
|
|
|
|
# Bcrypt uses it's own variation on base64 |
532
|
|
|
|
|
|
|
sub _en_bcrypt_base64 { |
533
|
|
|
|
|
|
|
my ($octets) = @_; |
534
|
|
|
|
|
|
|
my $text = encode_base64($octets, ''); |
535
|
|
|
|
|
|
|
$text =~ tr{A-Za-z0-9+/=}{./A-Za-z0-9}d; |
536
|
|
|
|
|
|
|
return $text; |
537
|
|
|
|
|
|
|
} |
538
|
|
|
|
|
|
|
|
539
|
|
|
|
|
|
|
|
540
|
|
|
|
|
|
|
# And the decoder of bcrypt's custom base64 |
541
|
|
|
|
|
|
|
sub _de_bcrypt_base64 { |
542
|
|
|
|
|
|
|
my ($text) = @_; |
543
|
|
|
|
|
|
|
$text =~ tr{./A-Za-z0-9}{A-Za-z0-9+/}; |
544
|
|
|
|
|
|
|
$text .= "=" x (3 - (length($text) + 3) % 4); |
545
|
|
|
|
|
|
|
return decode_base64($text); |
546
|
|
|
|
|
|
|
} |
547
|
|
|
|
|
|
|
|
548
|
|
|
|
|
|
|
|
549
|
|
|
|
|
|
|
register_plugin for_versions => [ 1, 2 ]; |
550
|
|
|
|
|
|
|
|
551
|
|
|
|
|
|
|
1; |
552
|
|
|
|
|
|
|
|
553
|
|
|
|
|
|
|
|
554
|
|
|
|
|
|
|
=head1 MORE INFORMATION |
555
|
|
|
|
|
|
|
|
556
|
|
|
|
|
|
|
=head2 Purpose |
557
|
|
|
|
|
|
|
|
558
|
|
|
|
|
|
|
The aim of this module is to help you store new passwords in a secure manner, |
559
|
|
|
|
|
|
|
whilst still being able to verify and upgrade older passwords. |
560
|
|
|
|
|
|
|
|
561
|
|
|
|
|
|
|
Cryptography is a vast and complex field. Many people try to roll their own |
562
|
|
|
|
|
|
|
methods for securing user data, but succeed only in coming up with |
563
|
|
|
|
|
|
|
a system that has little real security. |
564
|
|
|
|
|
|
|
|
565
|
|
|
|
|
|
|
This plugin provides a simple way of managing that complexity, allowing |
566
|
|
|
|
|
|
|
developers to follow crypto best practice without having to become an expert. |
567
|
|
|
|
|
|
|
|
568
|
|
|
|
|
|
|
|
569
|
|
|
|
|
|
|
=head2 Rationale |
570
|
|
|
|
|
|
|
|
571
|
|
|
|
|
|
|
The module defaults to hashing passwords using the bcrypt algorithm, returning them |
572
|
|
|
|
|
|
|
in RFC 2307 format. |
573
|
|
|
|
|
|
|
|
574
|
|
|
|
|
|
|
RFC 2307 describes an encoding system for passphrase hashes, as used in the "userPassword" |
575
|
|
|
|
|
|
|
attribute in LDAP databases. It encodes hashes as ASCII text, and supports several |
576
|
|
|
|
|
|
|
passphrase schemes by starting the encoding with an alphanumeric scheme identifier enclosed |
577
|
|
|
|
|
|
|
in braces. |
578
|
|
|
|
|
|
|
|
579
|
|
|
|
|
|
|
RFC 2307 only specifies the C, and C schemes - however in real-world usage, |
580
|
|
|
|
|
|
|
schemes that are salted are widely supported, and are thus provided by this module. |
581
|
|
|
|
|
|
|
|
582
|
|
|
|
|
|
|
Bcrypt is an adaptive hashing algorithm that is designed to resist brute |
583
|
|
|
|
|
|
|
force attacks by including a cost (aka work factor). This cost increases |
584
|
|
|
|
|
|
|
the computational effort it takes to compute the hash. |
585
|
|
|
|
|
|
|
|
586
|
|
|
|
|
|
|
SHA and MD5 are designed to be fast, and modern machines compute a billion |
587
|
|
|
|
|
|
|
hashes a second. With computers getting faster every day, brute forcing |
588
|
|
|
|
|
|
|
SHA hashes is a very real problem that cannot be easily solved. |
589
|
|
|
|
|
|
|
|
590
|
|
|
|
|
|
|
Increasing the cost of generating a bcrypt hash is a trivial way to make |
591
|
|
|
|
|
|
|
brute forcing ineffective. With a low cost setting, bcrypt is just as secure |
592
|
|
|
|
|
|
|
as a more traditional SHA+salt scheme, and just as fast. Increasing the cost |
593
|
|
|
|
|
|
|
as computers become more powerful keeps you one step ahead |
594
|
|
|
|
|
|
|
|
595
|
|
|
|
|
|
|
For a more detailed description of why bcrypt is preferred, see this article: |
596
|
|
|
|
|
|
|
L |
597
|
|
|
|
|
|
|
|
598
|
|
|
|
|
|
|
|
599
|
|
|
|
|
|
|
=head2 Configuration |
600
|
|
|
|
|
|
|
|
601
|
|
|
|
|
|
|
In your applications config file, you can set the default hashing algorithm, |
602
|
|
|
|
|
|
|
and the default settings for every supported algorithm. Calls to |
603
|
|
|
|
|
|
|
L will use the default settings |
604
|
|
|
|
|
|
|
for that algorithm specified in here. |
605
|
|
|
|
|
|
|
|
606
|
|
|
|
|
|
|
You can override these defaults when you call L. |
607
|
|
|
|
|
|
|
|
608
|
|
|
|
|
|
|
If you do no configuration at all, the default is to bcrypt with a cost of 4, and |
609
|
|
|
|
|
|
|
a strong psuedo-random salt. |
610
|
|
|
|
|
|
|
|
611
|
|
|
|
|
|
|
plugins: |
612
|
|
|
|
|
|
|
Passphrase: |
613
|
|
|
|
|
|
|
default: Bcrypt |
614
|
|
|
|
|
|
|
|
615
|
|
|
|
|
|
|
Bcrypt: |
616
|
|
|
|
|
|
|
cost: 8 |
617
|
|
|
|
|
|
|
|
618
|
|
|
|
|
|
|
|
619
|
|
|
|
|
|
|
=head2 Storage in a database |
620
|
|
|
|
|
|
|
|
621
|
|
|
|
|
|
|
You should be storing the RFC 2307 string in your database, it's the easiest way |
622
|
|
|
|
|
|
|
to use this module. You could store the C, C, and C |
623
|
|
|
|
|
|
|
separately, but this strongly discouraged. RFC 2307 strings are specifically |
624
|
|
|
|
|
|
|
designed for storing hashed passwords, and should be used wherever possible. |
625
|
|
|
|
|
|
|
|
626
|
|
|
|
|
|
|
The length of the string produced by L can |
627
|
|
|
|
|
|
|
vary dependent on your settings. Below is a table of the lengths generated |
628
|
|
|
|
|
|
|
using default settings. |
629
|
|
|
|
|
|
|
|
630
|
|
|
|
|
|
|
You will need to make sure your database columns are at least this long. |
631
|
|
|
|
|
|
|
If the string gets truncated, the password can I be validated. |
632
|
|
|
|
|
|
|
|
633
|
|
|
|
|
|
|
ALGORITHM LENGTH EXAMPLE RFC 2307 STRING |
634
|
|
|
|
|
|
|
|
635
|
|
|
|
|
|
|
Bcrypt 68 {CRYPT}$2a$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS |
636
|
|
|
|
|
|
|
SHA-512 118 {SSHA512}lZG4dZ5EU6dPEbJ1kBPPzEcupFloFSIJjiXCwMVxJXOy/x5qhBA5XH8FiUWj7u59onQxa97xYdqje/fwY5TDUcW1Urplf3KHMo9NO8KO47o= |
637
|
|
|
|
|
|
|
SHA-384 98 {SSHA384}SqZF5YYyk4NdjIM8YgQVfRieXDxNG0dKH4XBcM40Eblm+ribCzdyf0JV7i2xJvVHZsFSQNcuZPKtiTMzDyOU+w== |
638
|
|
|
|
|
|
|
SHA-256 74 {SSHA256}xsJHNzPlNCpOZ41OkTfQOU35ZY+nRyZFaM8lHg5U2pc0xT3DKNlGW2UTY0NPYsxU |
639
|
|
|
|
|
|
|
SHA-224 70 {SSHA224}FTHNkvKOdyX1d6f45iKLVxpaXZiHel8pfilUT1dIZ5u+WIUyhDGxLnx72X0= |
640
|
|
|
|
|
|
|
SHA-1 55 {SSHA}Qsaao/Xi/bYTRMQnpHuD3y5nj02wbdcw5Cek2y2nLs3pIlPh |
641
|
|
|
|
|
|
|
MD5 51 {SMD5}bgfLiUQWgzUm36+nBhFx62bi0xdwTp+UpEeNKDxSLfM= |
642
|
|
|
|
|
|
|
|
643
|
|
|
|
|
|
|
=head2 Common Mistakes |
644
|
|
|
|
|
|
|
|
645
|
|
|
|
|
|
|
Common mistakes people make when creating their own solution. If any of these |
646
|
|
|
|
|
|
|
seem familiar, you should probably be using this module |
647
|
|
|
|
|
|
|
|
648
|
|
|
|
|
|
|
=over |
649
|
|
|
|
|
|
|
|
650
|
|
|
|
|
|
|
=item Passwords are stored as plain text for a reason |
651
|
|
|
|
|
|
|
|
652
|
|
|
|
|
|
|
There is never a valid reason to store a password as plain text. |
653
|
|
|
|
|
|
|
Passwords should be reset and not emailed to customers when they forget. |
654
|
|
|
|
|
|
|
Support people should be able to login as a user without knowing the users password. |
655
|
|
|
|
|
|
|
No-one except the user should know the password - that is the point of authentication. |
656
|
|
|
|
|
|
|
|
657
|
|
|
|
|
|
|
=item No-one will ever guess our super secret algorithm! |
658
|
|
|
|
|
|
|
|
659
|
|
|
|
|
|
|
Unless you're a cryptography expert with many years spent studying |
660
|
|
|
|
|
|
|
super-complex maths, your algorithm is almost certainly not as secure |
661
|
|
|
|
|
|
|
as you think. Just because it's hard for you to break doesn't mean |
662
|
|
|
|
|
|
|
it's difficult for a computer. |
663
|
|
|
|
|
|
|
|
664
|
|
|
|
|
|
|
=item Our application-wide salt is "Sup3r_S3cret_L0ng_Word" - No-one will ever guess that. |
665
|
|
|
|
|
|
|
|
666
|
|
|
|
|
|
|
This is common misunderstanding of what a salt is meant to do. The purpose of a |
667
|
|
|
|
|
|
|
salt is to make sure the same password doesn't always generate the same hash. |
668
|
|
|
|
|
|
|
A fresh salt needs to be created each time you hash a password. It isn't meant |
669
|
|
|
|
|
|
|
to be a secret key. |
670
|
|
|
|
|
|
|
|
671
|
|
|
|
|
|
|
=item We generate our random salt using C. |
672
|
|
|
|
|
|
|
|
673
|
|
|
|
|
|
|
C isn't actually random, it's a non-unform pseudo-random number generator, |
674
|
|
|
|
|
|
|
and not suitable for cryptographic applications. Whilst this module also defaults to |
675
|
|
|
|
|
|
|
a PRNG, it is better than the one provided by C. Using a true RNG is a config |
676
|
|
|
|
|
|
|
option away, but is not the default as it it could potentially block output if the |
677
|
|
|
|
|
|
|
system does not have enough entropy to generate a truly random number |
678
|
|
|
|
|
|
|
|
679
|
|
|
|
|
|
|
=item We use C, and the salt is from C |
680
|
|
|
|
|
|
|
|
681
|
|
|
|
|
|
|
MD5 has been broken for many years. Commodity hardware can find a |
682
|
|
|
|
|
|
|
hash collision in seconds, meaning an attacker can easily generate |
683
|
|
|
|
|
|
|
the correct MD5 hash without using the correct password. |
684
|
|
|
|
|
|
|
|
685
|
|
|
|
|
|
|
=item We use C, and the salt is from C |
686
|
|
|
|
|
|
|
|
687
|
|
|
|
|
|
|
SHA isn't quite as broken as MD5, but it shares the same theoretical |
688
|
|
|
|
|
|
|
weaknesses. Even without hash collisions, it is vulnerable to brute forcing. |
689
|
|
|
|
|
|
|
Modern hardware is so powerful it can try around a billion hashes a second. |
690
|
|
|
|
|
|
|
That means every 7 chracter password in the range [A-Za-z0-9] can be cracked |
691
|
|
|
|
|
|
|
in one hour on your average desktop computer. |
692
|
|
|
|
|
|
|
|
693
|
|
|
|
|
|
|
=item If the only way to break the hash is to brute-force it, it's secure enough |
694
|
|
|
|
|
|
|
|
695
|
|
|
|
|
|
|
It is unlikely that your database will be hacked and your hashes brute forced. |
696
|
|
|
|
|
|
|
However, in the event that it does happen, or SHA512 is broken, using this module |
697
|
|
|
|
|
|
|
gives you an easy way to change to a different algorithm, while still allowing |
698
|
|
|
|
|
|
|
you to validate old passphrases |
699
|
|
|
|
|
|
|
|
700
|
|
|
|
|
|
|
=back |
701
|
|
|
|
|
|
|
|
702
|
|
|
|
|
|
|
|
703
|
|
|
|
|
|
|
=head1 KNOWN ISSUES |
704
|
|
|
|
|
|
|
|
705
|
|
|
|
|
|
|
If you see errors like this |
706
|
|
|
|
|
|
|
|
707
|
|
|
|
|
|
|
Wide character in subroutine entry |
708
|
|
|
|
|
|
|
|
709
|
|
|
|
|
|
|
or |
710
|
|
|
|
|
|
|
|
711
|
|
|
|
|
|
|
Input must contain only octets |
712
|
|
|
|
|
|
|
|
713
|
|
|
|
|
|
|
The C, C, and C algorithms can't handle chracters with an ordinal |
714
|
|
|
|
|
|
|
value above 255, producing errors like this if they encounter them. |
715
|
|
|
|
|
|
|
It is not possible for this plugin to automagically work out the correct |
716
|
|
|
|
|
|
|
encoding for a given string. |
717
|
|
|
|
|
|
|
|
718
|
|
|
|
|
|
|
If you see errors like this, then you probably need to use the L module |
719
|
|
|
|
|
|
|
to encode your text as UTF-8 (or whatever encoding it is) before giving it |
720
|
|
|
|
|
|
|
to C. |
721
|
|
|
|
|
|
|
|
722
|
|
|
|
|
|
|
Text encoding is a bag of hurt, and errors like this are probably indicitive |
723
|
|
|
|
|
|
|
of deeper problems within your app's code. |
724
|
|
|
|
|
|
|
|
725
|
|
|
|
|
|
|
You will save yourself a lot of trouble if you read up on the |
726
|
|
|
|
|
|
|
L module sooner rather than later. |
727
|
|
|
|
|
|
|
|
728
|
|
|
|
|
|
|
For further reading on UTF-8, unicode, and text encoding in perl, |
729
|
|
|
|
|
|
|
see L |
730
|
|
|
|
|
|
|
|
731
|
|
|
|
|
|
|
|
732
|
|
|
|
|
|
|
=head1 SEE ALSO |
733
|
|
|
|
|
|
|
|
734
|
|
|
|
|
|
|
L, L, L, L |
735
|
|
|
|
|
|
|
|
736
|
|
|
|
|
|
|
|
737
|
|
|
|
|
|
|
=head1 AUTHOR |
738
|
|
|
|
|
|
|
|
739
|
|
|
|
|
|
|
James Aitken |
740
|
|
|
|
|
|
|
|
741
|
|
|
|
|
|
|
|
742
|
|
|
|
|
|
|
=head1 COPYRIGHT AND LICENSE |
743
|
|
|
|
|
|
|
|
744
|
|
|
|
|
|
|
This software is copyright (c) 2012 by James Aitken. |
745
|
|
|
|
|
|
|
|
746
|
|
|
|
|
|
|
This is free software; you can redistribute it and/or modify it under |
747
|
|
|
|
|
|
|
the same terms as the Perl 5 programming language system itself. |
748
|
|
|
|
|
|
|
|
749
|
|
|
|
|
|
|
=cut |