File Coverage

blib/lib/Text/Password/AutoMigration.pm

Criterion	Covered	Total	%
statement	12	12	100.0
branch			n/a
condition			n/a
subroutine	4	4	100.0
pod			n/a
total	16	16	100.0

line	stmt	sub	time	code
1				package Text::Password::AutoMigration;
2				our $VERSION = "0.18";
3
4	2	2	71991	use autouse 'Carp' => qw(croak carp);
	2		1659
	2		16
5	2	2	1241	use Moo;
	2		15710
	2		9
6	2	2	3824	use strictures 2;
	2		3421
	2		87
7				extends 'Text::Password::SHA';
8
9				=encoding utf-8
10
11				=head1 NAME
12
13				Text::Password::AutoMigration - generate and verify Password with any contexts
14
15				=head1 SYNOPSIS
16
17				my $pwd = Text::Password::AutoMigration->new();
18				my( $raw, $hash ) = $pwd->generate(); # list context is required
19				my $input = $req->body_parameters->{passwd};
20				my $data = $pwd->encrypt($input); # you don't have to care about salt
21				my $flag = $pwd->verify( $input, $data );
22
23				=head1 DESCRIPTION
24
25				Text::Password::AutoMigration is a module for some lasy Administrators.
26
27				It would help you to migrate old hash what has vulnerability
28				such as encrypted by perl, MD5, SHA-1 or even if it was with SHA-256 to SHA-512.
29
30				The method I<verify()> automatically detects the algorithm which is applied to the hash
31				with B<CORE::crypt>, B<MD5>, B<SHA-1 by hex>, B<SHA-256> and of course B<SHA-512>.
32
33				And every I<verify()> B<returns a brand new hash> generated by using B<with SHA-512>.
34
35				Therefore all you have to do is to replace the old hash with the new one on your Databases.
36
37				=head2 Constructor and initialization
38
39				=head3 new()
40
41				No arguments are required. But you can set some parameters.
42
43				=over
44
45				=item default( I<Int> )
46
47				You can set default length with using 'default' argument like below:
48
49				$pwd = Text::Password::AutoMiglation->new( default => 8 );
50
51
52				It must be an Int, defaults to 10.
53
54				=item readablity( I<Bool> )
55
56				You can set default strength for password with usnig 'readablity' argument like below:
57
58				$pwd = Text::Password::AutoMiglation->new( readability => 0 );
59
60
61				It must be a Boolean, defaults to 1.
62
63				If it was false, I<generate()> starts to return stronger passwords with charactors hard to read.
64
65				=item migrate( I<Bool> )
66
67				It must be a Boolean, defaults to 1.
68
69				If you've already replaced all hash or started to make new applications with this module,
70
71				you can call the constructor with I<migrate =E<gt> 0>.
72
73				Then I<verify()> would not return a new hash but always 1.
74
75				It may help you a little faster without any change of your code.
76
77				=cut
78
79	2	2	1643	use Types::Standard qw(Bool);
	2		231329
	2		20
80				has migrate => ( is => 'rw', isa => Bool, default => 1 );
81
82				=back
83
84				=head2 Methods and Subroutines
85
86				=head3 verify( $raw, $hash )
87
88				To tell the truth, this is the most useful method of this module.
89
90				it Returns a true strings instead of boolean if the verification succeeds.
91
92				Every value is B<brand new hash from SHA-512>
93				because it is actually true in Perl anyway.
94
95				So you can replace hash in your Database easily like below:
96
97				my $pwd = Text::Password::AutoMigration->new();
98
99				my $dbh = DBI->connect(...);
100				my $db_hash_ref = $dbh->fetchrow_hashref(...);
101				my $param = $req->body_parameters;
102
103				my $hash = $pwd->verify( $param->{passwd}, $db_hash_ref->{passwd} );
104				my $verified = length $hash;
105				if ( $verified ) { # don't have to execute it every time
106				my $sth = $dbh->prepare('UPDATE DB SET passwd=? WHERE uid =?') or die $dbh->errstr;
107				$sth->excute( $hash, $param->{uid} ) or die $sth->errstr;
108				}
109
110				New hash length is 100 (if it defaults).
111				So you have to change the Table with like below:
112
113				ALTER TABLE User MODIFY passwd VARCHAR(100);
114
115				=cut
116
117				around verify => sub {
118				my ( $orig, $self ) = ( shift, shift );
119				return 0 unless $self->$orig(@_);
120				return $self->migrate() ? $self->encrypt(@_) : 1;
121				};
122
123				=head3 nonce( I<Int> )
124
125				generates the random strings with enough strength.
126
127				the length defaults to 10 \|\| $self->default().
128
129				=head3 encrypt( I<Str> )
130
131				returns hash with unix_sha512_crypt()
132
133				enough strength salts will be made automatically.
134
135				=head3 generate( I<Int> )
136
137				generates pair of new password and its hash.
138
139				less readable characters(0Oo1Il\|!2Zz5sS$6b9qCcKkUuVvWwXx.,:;~-^'"`) are forbidden
140				unless $self->readability is 0.
141
142				the length defaults to 10 \|\| $self->default().
143
144				B<DON'T TRUST> this method.
145
146				According to L<Password expert says he was wrong\|https://www.usatoday.com/story/news/nation-now/2017/08/09/password-expert-says-he-wrong-numbers-capital-letters-and-symbols-useless/552013001/>,
147				it's not a safe way. So, I will rewrite this method as soon as I find the better way.
148
149				=cut
150
151				1;
152
153				__END__
154
155				=head1 SEE ALSO
156
157				=over
158
159				=item L<GitHub\|https://github.com/worthmine/Text-Password-AutoMigration>
160
161				=item L<CPAN\|http://search.cpan.org/perldoc?Text%3A%3APassword%3A%3AAutoMigration>
162
163				=item L<https://shattered.io/>
164
165				=back
166
167				=head1 LICENSE
168
169				Copyright (C) Yuki Yoshida(worthmine).
170
171				This library is free software; you can redistribute it and/or modify
172				it under the same terms as Perl itself.
173
174				=head1 AUTHOR
175
176				Yuki Yoshida E<lt>worthmine@users.noreply.github.comE<gt>