Dancer2-Plugin-Passphrase-3.4.1/0000755000175000017500000000000014245105073014455 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/CHANGES0000644000175000017500000000433514245104553015457 0ustar apmapmRevision history for Dancer2-Plugin-Passphrase 3.4.1 Mon 30 May 11:07:23 CEST 2022 * Update dependencies to allow removal of Digest::Bcrypt monkeypatch 3.4.0 Sat 28 May 12:45:00 CEST 2020 * Changed bcrypt backend in Digest::Bcrypt v1.210 (GH#5 Peter Mottram) * Mark module as deprecated 3.3.4 Mon 11 April 18:55:00 EDT 220 * Fix example for Bcrypt configuration in POD (Sergiy Borodych) * Set bcrypt cost from YAML config (Jeremi M Gosney) 3.3.3 Mon 22 Oct 15:00:50 CEST 2018 * Fix typos in documentation (Mohammad S Anwar) 3.3.2 Sun 21 Oct 13:40:45 CEST 2018 * Fix typos in documentation (GH#12 Nuno Carvalho) * reduce min Perl requirement to 5.8.1 from 5.10.1 * Fix documentation for optional args for generate (thanks to Tom Adams) 3.3.0 2016-10-04 [ D2P2 ] No longer compatible with Dancer2 prior to plugin2 release. 3.2.2 2015-12-30 [ D2P2 ] Compatible with the new Dancer2::Plugin2 3.0.2 2015-03-10 [ NICE! ] Move plugin_setting to on_plugin_import. This makes $dsl->passphrase callable from other plugins! 3.0.1 2015-03-09 [ MISC ] Removed some leftovers. 3.0.0 2015-03-09 [ Remove AUTO STRINGIFICATION ] This version looks like 2.0.5 :) 2.0.6 2014-12-16 [ AUTO STRINGIFICATION IS DEPRECATED ] This version brings back the overloading but it will carp! You must use $phrase->rfc2307() to get a text string. 2.0.5 2014-12-12 [ Sawyer X ] Major cleanup: it works now: The original structure was awkward. This is fixed and working with the original tests. There are now three decoupled parts: * Dancer2::Plugin::Passphrase: Provide the 'generate' keyword for generating passphrases. * Dancer2::Plugin::Passphrase::Core: The majority of the actual implementation. When you call the 'generate' keyword it creates an object of Dancer2::Plugin::Passphrase::Core. The original design would actually create an object of the plugin itself, which is risky and confusing. When you call methods, it's actually called on this object. * Dancer2::Plugin::Passphrase::Hashed: This is a data object representing the hashed passphrase. 2.0.4 2014-11-22 [ MISC ] * New Makfile 2.0.3 2014-11-10 [ MISC ] * D2 version 0.0.1 2011-09-06 ** First Draft ** Dancer2-Plugin-Passphrase-3.4.1/t/0000755000175000017500000000000014245105073014720 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/t/002_pod_coverage.t0000644000175000017500000000122012642460450020120 0ustar apmapmuse strict; use warnings; use Test::More; eval "use Test::Pod::Coverage 1.08"; plan skip_all => "Test::Pod::Coverage 1.08 required for testing POD coverage" if $@; plan tests => 1; my $d2_subs = qr{ ( ClassHooks | PluginKeyword | dancer_app | execute_plugin_hook | hook | keywords | on_plugin_import | plugin_args | plugin_setting | register | register_hook | register_plugin | request | var ) }x; pod_coverage_ok( "Dancer2::Plugin::Passphrase", { also_private => [ $d2_subs ] }, "Dancer2::Plugin::Passphrase has full POD coverage" ); Dancer2-Plugin-Passphrase-3.4.1/t/006_return_object.t0000644000175000017500000000512114245101174020334 0ustar apmapmuse Test::More tests => 20; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; use MIME::Base64 qw(decode_base64 encode_base64); my $secret = "Super Secret Squirrel"; my $object = passphrase($secret)->generate; isa_ok( $object, 'Dancer2::Plugin::Passphrase::Hashed' ); ok($object->rfc2307, 'Contains RFC 2307 representation'); ok($object->algorithm eq 'Bcrypt', 'Contains correct scheme'); ok($object->cost eq '04', 'Contains correct cost'); ok($object->hash_raw, 'Contains raw salt'); ok($object->hash_hex, 'Contains hex hash'); ok($object->hash_base64, 'Contains base64 hash'); ok($object->salt_raw, 'Contains raw salt'); ok($object->salt_hex, 'Contains hex salt'); ok($object->salt_base64, 'Contains base64 salt'); ok($object->plaintext eq $secret, 'Contains correct plaintext'); # Test that the salt / hash doesn't get changed when we create the RFC2307 string my $salted_object = passphrase($secret)->generate({ algorithm => 'SHA-256', salt => 'A Bad Salt' }); my ($scheme, $settings) = ($salted_object->rfc2307 =~ m/^{(\w+)}(.*)/s); my $extracted_salt = substr(decode_base64($settings), 256 / 8); my $extracted_hash = substr(decode_base64($settings), 0, 256 / 8); is( $extracted_salt, $salted_object->salt_raw, "Extracted raw salt is the same as the defined raw salt" ); is( encode_base64($extracted_salt,''), $salted_object->salt_base64, "Extracted base64 salt is the same as the defined base64 salt" ); is( unpack("H*", $extracted_salt), $salted_object->salt_hex, "Extracted hex salt is the same as the defined hex salt" ); is( $extracted_hash, $salted_object->hash_raw, "Extracted raw hash is the same as the defined raw hash" ); is( encode_base64($extracted_hash,''), $salted_object->hash_base64, "Extracted base64 hash is the same as the defined base64 hash" ); is( unpack("H*", $extracted_hash), $salted_object->hash_hex, "Extracted hex hash is the same as the defined hex hash" ); # Do check defined but empty salts too. my $saltless_object = passphrase($secret)->generate({ algorithm => 'SHA-1', salt => '' }); ok(defined $saltless_object->salt_raw, 'Contains a defined, but empty raw salt'); ok(defined $saltless_object->salt_hex, 'Contains a defined, but empty hex salt'); ok(defined $saltless_object->salt_base64, 'Contains a defined, but empty base64 salt'); Dancer2-Plugin-Passphrase-3.4.1/t/001_basics.t0000644000175000017500000000013312642460450016730 0ustar apmapmuse strict; use warnings; use Test::More tests => 1; use_ok 'Dancer2::Plugin::Passphrase'; Dancer2-Plugin-Passphrase-3.4.1/t/005_random_passphrase.t0000644000175000017500000000074412642460450021211 0ustar apmapmuse Test::More tests => 3; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $with_defaults = passphrase->generate_random; my $extra_length = passphrase->generate_random({ length => 32 }); my $scouse_password = passphrase->generate_random({ charset => ['a'], length => 3 }); ok($with_defaults, "Basic password generation"); ok(length $extra_length eq 32, "Custom password length"); ok($scouse_password eq 'aaa', "Custom chracter set"); Dancer2-Plugin-Passphrase-3.4.1/t/009_exception_handling.t0000644000175000017500000000072312642460450021343 0ustar apmapmuse Test::More tests => 2; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; eval { passphrase($secret)->matches('not an rfc2307 string') }; like $@, qr/An RFC 2307 compliant string must be passed to matches/i, 'Dies on invalid RFC 2307 string'; eval { passphrase($secret)->matches('{CRYPT}$ Almost $ An RFC 2307 String') }; like $@, qr/Unknown CRYPT format/i, 'Dies on almost valid RFC 2307 string'; Dancer2-Plugin-Passphrase-3.4.1/t/013_hashes_generated_elsewhere.t0000644000175000017500000000604114245104104023017 0ustar apmapmuse Test::More tests => 30; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; # Test a bunch of bcyrpt hashes generated from other places # From v1.0.0 of Dancer::Plugin::Passphrase. Perl 5.14.2, OS X 10.8.2 my @old_dpp_version = qw( {CRYPT}$2a$04$utiZ69Z.1fRZZmxNjLRv/eLyPUzWLRaCO26OB/HsbyvZ4dReU.ct6 {CRYPT}$2a$04$x9.J131nELn13EYvG2b.DuE4J.Z36wUaf1n9zfT91wloa/Nn5BbQ. {CRYPT}$2a$04$8g0azf0s7lyNdnMHF0WQCO1q2Wt1tCdMOecTN46.n2iyOmsW9WKqq {CRYPT}$2a$04$c2l3u0gkT7nbKDX4ZoaPQuGetzOtpBUilv8U5UTCphdLbuL/JsbuC {CRYPT}$2a$04$1VmfVtTUto/vo3YXOnN7hOpgC1pm4hSwobSrmYijPR25czhOv7pWS {CRYPT}$2a$04$wZwWOWvxOudBpbaC6tG0h.QC8TyNsfK.7mnoJXCvEb/PEPr/28Qji {CRYPT}$2a$04$dgOLegmH50m5LzkU27BKkOkHtx4ov2MW4SlhV370y7/FOzQRpB0IK {CRYPT}$2a$04$LW2wzn2JmwwXvwKbztxwoeWE/1RKyXLSVHH4sgAb8bRO6200c.0t. {CRYPT}$2a$04$4WacfXK9Dle2lx2IhCi0MuL2TNgRUrXvC2BRxs.yNmb.e.3oS4EZW {CRYPT}$2a$04$LCAxXIiEjzd4ttw/fLw1FOvBy6BK8pG/5PccAiOdVD5adWBwq1Jw. ); # From 0.008 of Authen::Passphrase::BlowfishCrypt. Perl 5.14.2, OS X 10.8.2 my @authen_passphrase = qw( {CRYPT}$2a$04$utiZ69Z.1fRZZmxNjLRv/eLyPUzWLRaCO26OB/HsbyvZ4dReU.ct6 {CRYPT}$2a$04$x9.J131nELn13EYvG2b.DuE4J.Z36wUaf1n9zfT91wloa/Nn5BbQ. {CRYPT}$2a$04$8g0azf0s7lyNdnMHF0WQCO1q2Wt1tCdMOecTN46.n2iyOmsW9WKqq {CRYPT}$2a$04$c2l3u0gkT7nbKDX4ZoaPQuGetzOtpBUilv8U5UTCphdLbuL/JsbuC {CRYPT}$2a$04$1VmfVtTUto/vo3YXOnN7hOpgC1pm4hSwobSrmYijPR25czhOv7pWS {CRYPT}$2a$04$wZwWOWvxOudBpbaC6tG0h.QC8TyNsfK.7mnoJXCvEb/PEPr/28Qji {CRYPT}$2a$04$dgOLegmH50m5LzkU27BKkOkHtx4ov2MW4SlhV370y7/FOzQRpB0IK {CRYPT}$2a$04$LW2wzn2JmwwXvwKbztxwoeWE/1RKyXLSVHH4sgAb8bRO6200c.0t. {CRYPT}$2a$04$4WacfXK9Dle2lx2IhCi0MuL2TNgRUrXvC2BRxs.yNmb.e.3oS4EZW {CRYPT}$2a$04$LCAxXIiEjzd4ttw/fLw1FOvBy6BK8pG/5PccAiOdVD5adWBwq1Jw. ); # From v3.0.1 of the bcrypt_ruby gem. Ruby 1.9.3p125, OS X 10.8.2 my @rubygems = qw( {CRYPT}$2a$04$1JI5Ldcddt9.NruLgsB2cetbHwLrvD5ZsDZO6r/jZKcDc3aRkV8ny {CRYPT}$2a$04$GWNNixiHf63wc.6.Ebrrb.vci5HKNhd2.DMXAS5XZcbLSPUdIwjfe {CRYPT}$2a$04$wcvVw7eMULQ0moXOYhSOkeGdJ6MDlegt1/rnVcwP/D6Bg8G2kbY72 {CRYPT}$2a$04$rtbeTZqiL8E3053U6yKkCOd.9UJ.ITsHjk3zA8mXdTUywXygAik82 {CRYPT}$2a$04$K1DolOJ1aJSpTzVnhCAIU.aCHO6ohdBMA39QyiEAbINQzN7cPBPCa {CRYPT}$2a$04$yIPpoJ6r8Nm1cO0PTyTbzu8A8XHSUMC8/5CPmUG.jqiet9jhBjHIC {CRYPT}$2a$04$E1wjvpG6ykfDqArV107DY.DoVGO8dBJSM03kyaBJjQdv98BEON0jq {CRYPT}$2a$04$ZCwnOt5DQQ4yhhH7.iwH/unAnxHWt.e0ZGuZgcrNi7QQQlS7Enk/m {CRYPT}$2a$04$yr17B8vIkiVilVDn49rE.uWL0p6a2x5gI/GcoojvYhTetVQQc5jOm {CRYPT}$2a$04$oacLS1vbH0qh8XFEJmImLuy9sP8tgM74iah1bbY26kIgmDxTgDgSq ); # The actual tests for my $rfc2307 (@old_dpp_version) { ok(passphrase($secret)->matches($rfc2307), "Old Dancer::Plugin::Passphrase Bcrypt hashes can be validated"); } for my $rfc2307 (@authen_passphrase) { ok(passphrase($secret)->matches($rfc2307), "Authen::Passphrase Bcrypt hashes can be validated"); } for my $rfc2307 (@rubygems) { ok(passphrase($secret)->matches($rfc2307), "Ruby Bcrypt hashes can be validated"); } Dancer2-Plugin-Passphrase-3.4.1/t/008_unicode_matching.t0000644000175000017500000000311014245104076020771 0ustar apmapmuse Test::More tests => 8; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; use Encode; # Unicode Character 'PILE OF POO'. my $secret = "\x{1F4A9}"; my $utf8_secret = Encode::encode_utf8("\x{1F4A9}"); # SHA-1 Tests my $sha_utf8 = passphrase($utf8_secret)->generate({ algorithm => 'SHA-1' })->rfc2307; ok(passphrase($utf8_secret)->matches($sha_utf8), 'UTF8 matches UTF8 for SHA-1'); eval { passphrase($secret)->generate({ algorithm => 'SHA-1' })->rfc2307; }; like $@, qr/Wide character in subroutine entry/i, 'SHA-1 needs encoded text'; # SHA-256 Tests my $sha_256_utf8 = passphrase($utf8_secret)->generate({ algorithm => 'SHA-256' })->rfc2307; ok(passphrase($utf8_secret)->matches($sha_256_utf8), 'UTF8 matches UTF8 for SHA-256'); eval { passphrase($secret)->generate({ algorithm => 'SHA-256' })->rfc2307; }; like $@, qr/Wide character in subroutine entry/i, 'SHA-256 needs encoded text'; # MD5 Tests my $md5_utf8 = passphrase($utf8_secret)->generate({ algorithm => 'MD5' })->rfc2307; ok(passphrase($utf8_secret)->matches($md5_utf8), 'UTF8 matches UTF8 for MD5'); eval { passphrase($secret)->generate({ algorithm => 'MD5' })->rfc2307; }; like $@, qr/Wide character in subroutine entry/i, 'MD5 needs encoded text'; # Bcrypt Tests my $bcrypt_utf8 = passphrase($utf8_secret)->generate({ algorithm => 'Bcrypt' })->rfc2307; ok(passphrase($utf8_secret)->matches($bcrypt_utf8), 'UTF8 matches UTF8 for Bcrypt'); eval { passphrase($secret)->generate({ algorithm => 'Bcrypt' })->rfc2307; }; like $@, qr/Wide character in subroutine entry/i, 'Bcrypt needs encoded text'; Dancer2-Plugin-Passphrase-3.4.1/t/011_alternative_bcrypt.t0000644000175000017500000000116312642460450021372 0ustar apmapmuse Test::More tests => 3; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; my $two_a = '{CRYPT}$2a$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS'; my $two_x = '{CRYPT}$2x$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS'; my $two_y = '{CRYPT}$2y$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS'; ok(passphrase($secret)->matches($two_a), 'Matches $2a$ (ambiguous bcrypt)'); ok(passphrase($secret)->matches($two_x), 'Matches $2x$ (broken bcrypt)'); ok(passphrase($secret)->matches($two_a), 'Matches $2y$ (new standard bcrypt)'); Dancer2-Plugin-Passphrase-3.4.1/t/004_all_algorithm_matching.t0000644000175000017500000000150512642460450022163 0ustar apmapmuse Test::More tests => 26; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; for (qw(MD5 SHA-1 SHA-224 SHA-256 SHA-384 SHA-512 Bcrypt)) { my $rfc2307 = passphrase($secret)->generate({ algorithm => $_ })->rfc2307; ok(passphrase($secret)->matches($rfc2307), "With Salt - Match plaintext to hash => $_"); ok(!passphrase('WRONG')->matches($rfc2307), "With Salt - Incorrect passwords should be rejected => $_"); } for (qw(MD5 SHA-1 SHA-224 SHA-256 SHA-384 SHA-512)) { my $rfc2307 = passphrase($secret)->generate({ algorithm => $_, salt => '' })->rfc2307; ok(passphrase($secret)->matches($rfc2307), "No Salt - Match plaintext to hash => $_"); ok(!passphrase('WRONG')->matches($rfc2307), "No Salt - Incorrect passwords should be rejected => $_"); } Dancer2-Plugin-Passphrase-3.4.1/t/003_default_settings.t0000644000175000017500000000065614245101174021040 0ustar apmapmuse strict; use warnings; use Test::More tests => 3; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; my $rfc2307 = passphrase($secret)->generate->rfc2307; like($rfc2307, qr/^{CRYPT}\$2a\$04\$/, 'RFC compliant hash generated'); ok(passphrase($secret)->matches($rfc2307), 'Match plaintext to hash'); ok(!passphrase('WRONG')->matches($rfc2307), 'Incorrect passwords should be rejected'); Dancer2-Plugin-Passphrase-3.4.1/t/007_no_salt.t0000644000175000017500000000103512642460450017133 0ustar apmapmuse Test::More tests => 2; use strict; use warnings; use Dancer2; use Dancer2::Plugin::Passphrase; my $secret = "Super Secret Squirrel"; my $known_value = '{SHA}lmrkJArUS4AvuHtllhJG2hOBlcE='; # Bcrypt has to have a salt, so we pick a different algorithm my $rfc2307 = passphrase($secret)->generate({ algorithm => 'SHA-1', salt => '' })->rfc2307; ok(passphrase($secret)->matches($known_value), "Match plaintext to it's pre-computed hash"); ok(passphrase($secret)->matches($rfc2307), "Match plaintext to it's generated hash"); Dancer2-Plugin-Passphrase-3.4.1/README.markdown0000644000175000017500000001202112642460450017154 0ustar apmapm# NAME Dancer2::Plugin::Passphrase - Passphrases and Passwords as objects for Dancer2 # SYNOPSIS This plugin manages the hashing of passwords for Dancer2 apps, allowing developers to follow cryptography best practices without having to become a cryptography expert. It uses the bcrypt algorithm as the default, while also supporting any hashing function provided by [Digest](https://metacpan.org/pod/Digest) # MORE INFORMATION ## Purpose The aim of this module is to help you store new passwords in a secure manner, whilst still being able to verify and upgrade older passwords. Cryptography is a vast and complex field. Many people try to roll their own methods for securing user data, but succeed only in coming up with a system that has little real security. This plugin provides a simple way of managing that complexity, allowing developers to follow crypto best practice without having to become an expert. ## Rationale The module defaults to hashing passwords using the bcrypt algorithm, returning them in RFC 2307 format. RFC 2307 describes an encoding system for passphrase hashes, as used in the "userPassword" attribute in LDAP databases. It encodes hashes as ASCII text, and supports several passphrase schemes by starting the encoding with an alphanumeric scheme identifier enclosed in braces. RFC 2307 only specifies the `MD5`, and `SHA` schemes - however in real-world usage, schemes that are salted are widely supported, and are thus provided by this module. Bcrypt is an adaptive hashing algorithm that is designed to resist brute force attacks by including a cost (aka work factor). This cost increases the computational effort it takes to compute the hash. SHA and MD5 are designed to be fast, and modern machines compute a billion hashes a second. With computers getting faster every day, brute forcing SHA hashes is a very real problem that cannot be easily solved. Increasing the cost of generating a bcrypt hash is a trivial way to make brute forcing ineffective. With a low cost setting, bcrypt is just as secure as a more traditional SHA+salt scheme, and just as fast. Increasing the cost as computers become more powerful keeps you one step ahead For a more detailed description of why bcrypt is preferred, see this article: [http://codahale.com/how-to-safely-store-a-password/](http://codahale.com/how-to-safely-store-a-password/) ## Common Mistakes Common mistakes people make when creating their own solution. If any of these seem familiar, you should probably be using this module - Passwords are stored as plain text for a reason There is never a valid reason to store a password as plain text. Passwords should be reset and not emailed to customers when they forget. Support people should be able to login as a user without knowing the users password. No-one except the user should know the password - that is the point of authentication. - No-one will ever guess our super secret algorithm! Unless you're a cryptography expert with many years spent studying super-complex maths, your algorithm is almost certainly not as secure as you think. Just because it's hard for you to break doesn't mean it's difficult for a computer. - Our application-wide salt is "Sup3r\_S3cret\_L0ng\_Word" - No-one will ever guess that. This is common misunderstanding of what a salt is meant to do. The purpose of a salt is to make sure the same password doesn't always generate the same hash. A fresh salt needs to be created each time you hash a password. It isn't meant to be a secret key. - We generate our random salt using `rand`. `rand` isn't actually random, it's a non-unform pseudo-random number generator, and not suitable for cryptographic applications. Whilst this module also defaults to a PRNG, it is better than the one provided by `rand`. Using a true RNG is a config option away, but is not the default as it it could potentially block output if the system does not have enough entropy to generate a truly random number - We use `md5(pass.salt)`, and the salt is from `/dev/random` MD5 has been broken for many years. Commodity hardware can find a hash collision in seconds, meaning an attacker can easily generate the correct MD5 hash without using the correct password. - We use `sha(pass.salt)`, and the salt is from `/dev/random` SHA isn't quite as broken as MD5, but it shares the same theoretical weaknesses. Even without hash collisions, it is vulnerable to brute forcing. Modern hardware is so powerful it can try around a billion hashes a second. That means every 7 chracter password in the range \[A-Za-z0-9\] can be cracked in one hour on your average desktop computer. - If the only way to break the hash is to brute-force it, it's secure enough It is unlikely that your database will be hacked and your hashes brute forced. However, in the event that it does happen, or SHA512 is broken, using this module gives you an easy way to change to a different algorithm, while still allowing you to validate old passphrases Dancer2-Plugin-Passphrase-3.4.1/MANIFEST0000644000175000017500000000115714245105073015612 0ustar apmapmCHANGES lib/Dancer2/Plugin/Passphrase.pm lib/Dancer2/Plugin/Passphrase/Core.pm lib/Dancer2/Plugin/Passphrase/Hashed.pm LICENSE Makefile.PL MANIFEST This list of files README.markdown t/001_basics.t t/002_pod_coverage.t t/003_default_settings.t t/004_all_algorithm_matching.t t/005_random_passphrase.t t/006_return_object.t t/007_no_salt.t t/008_unicode_matching.t t/009_exception_handling.t t/011_alternative_bcrypt.t t/013_hashes_generated_elsewhere.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) Dancer2-Plugin-Passphrase-3.4.1/META.yml0000644000175000017500000000167314245105073015735 0ustar apmapm--- abstract: 'Passphrases and Passwords as objects for Dancer2' author: - 'Henk van Oers ' build_requires: ExtUtils::MakeMaker: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.64, CPAN::Meta::Converter version 2.150010' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Dancer2-Plugin-Passphrase no_index: directory: - t - inc requires: Crypt::Bcrypt: '0.006' Dancer2: '0.200000' Data::Entropy: '0.007' Digest::Bcrypt: '1.212' Digest::SHA: '5.74' Test::More: '0' perl: '5.008001' resources: bugtracker: https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/issues homepage: https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/ repository: https://github.com/PerlDancer/Dancer2-Plugin-Passphrase version: v3.4.1 x_serialization_backend: 'CPAN::Meta::YAML version 0.018' Dancer2-Plugin-Passphrase-3.4.1/LICENSE0000644000175000017500000002130712642460450015467 0ustar apmapmThe Artistic License 2.0 Copyright (c) 2014 Henk van Oers Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble This license establishes the terms under which a given free software Package may be copied, modified, distributed, and/or redistributed. The intent is that the Copyright Holder maintains some artistic control over the development of that Package while still keeping the Package available as open source and free software. You are always permitted to make arrangements wholly outside of this license directly with the Copyright Holder of a given Package. If the terms of this license do not permit the full use that you propose to make of the Package, you should contact the Copyright Holder and seek a different licensing arrangement. Definitions "Copyright Holder" means the individual(s) or organization(s) named in the copyright notice for the entire Package. "Contributor" means any party that has contributed code or other material to the Package, in accordance with the Copyright Holder's procedures. "You" and "your" means any person who would like to copy, distribute, or modify the Package. "Package" means the collection of files distributed by the Copyright Holder, and derivatives of that collection and/or of those files. A given Package may consist of either the Standard Version, or a Modified Version. "Distribute" means providing a copy of the Package or making it accessible to anyone else, or in the case of a company or organization, to others outside of your company or organization. "Distributor Fee" means any fee that you charge for Distributing this Package or providing support for this Package to another party. It does not mean licensing fees. "Standard Version" refers to the Package if it has not been modified, or has been modified only in ways explicitly requested by the Copyright Holder. "Modified Version" means the Package, if it has been changed, and such changes were not explicitly requested by the Copyright Holder. "Original License" means this Artistic License as Distributed with the Standard Version of the Package, in its current version or as it may be modified by The Perl Foundation in the future. "Source" form means the source code, documentation source, and configuration files for the Package. "Compiled" form means the compiled bytecode, object code, binary, or any other form resulting from mechanical transformation or translation of the Source form. Permission for Use and Modification Without Distribution (1) You are permitted to use the Standard Version and create and use Modified Versions for any purpose without restriction, provided that you do not Distribute the Modified Version. Permissions for Redistribution of the Standard Version (2) You may Distribute verbatim copies of the Source form of the Standard Version of this Package in any medium without restriction, either gratis or for a Distributor Fee, provided that you duplicate all of the original copyright notices and associated disclaimers. At your discretion, such verbatim copies may or may not include a Compiled form of the Package. (3) You may apply any bug fixes, portability changes, and other modifications made available from the Copyright Holder. The resulting Package will still be considered the Standard Version, and as such will be subject to the Original License. Distribution of Modified Versions of the Package as Source (4) You may Distribute your Modified Version as Source (either gratis or for a Distributor Fee, and with or without a Compiled form of the Modified Version) provided that you clearly document how it differs from the Standard Version, including, but not limited to, documenting any non-standard features, executables, or modules, and provided that you do at least ONE of the following: (a) make the Modified Version available to the Copyright Holder of the Standard Version, under the Original License, so that the Copyright Holder may include your modifications in the Standard Version. (b) ensure that installation of your Modified Version does not prevent the user installing or running the Standard Version. In addition, the Modified Version must bear a name that is different from the name of the Standard Version. (c) allow anyone who receives a copy of the Modified Version to make the Source form of the Modified Version available to others under (i) the Original License or (ii) a license that permits the licensee to freely copy, modify and redistribute the Modified Version using the same licensing terms that apply to the copy that the licensee received, and requires that the Source form of the Modified Version, and of any works derived from it, be made freely available in that license fees are prohibited but Distributor Fees are allowed. Distribution of Compiled Forms of the Standard Version or Modified Versions without the Source (5) You may Distribute Compiled forms of the Standard Version without the Source, provided that you include complete instructions on how to get the Source of the Standard Version. Such instructions must be valid at the time of your distribution. If these instructions, at any time while you are carrying out such distribution, become invalid, you must provide new instructions on demand or cease further distribution. If you provide valid instructions or cease distribution within thirty days after you become aware that the instructions are invalid, then you do not forfeit any of your rights under this license. (6) You may Distribute a Modified Version in Compiled form without the Source, provided that you comply with Section 4 with respect to the Source of the Modified Version. Aggregating or Linking the Package (7) You may aggregate the Package (either the Standard Version or Modified Version) with other packages and Distribute the resulting aggregation provided that you do not charge a licensing fee for the Package. Distributor Fees are permitted, and licensing fees for other components in the aggregation are permitted. The terms of this license apply to the use and Distribution of the Standard or Modified Versions as included in the aggregation. (8) You are permitted to link Modified and Standard Versions with other works, to embed the Package in a larger work of your own, or to build stand-alone binary or bytecode versions of applications that include the Package, and Distribute the result without restriction, provided the result does not expose a direct interface to the Package. Items That are Not Considered Part of a Modified Version (9) Works (including, but not limited to, modules and scripts) that merely extend or make use of the Package, do not, by themselves, cause the Package to be a Modified Version. In addition, such works are not considered parts of the Package itself, and are not subject to the terms of this license. General Provisions (10) Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license. (11) If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license. (12) This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder. (13) This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed. (14) Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Dancer2-Plugin-Passphrase-3.4.1/META.json0000644000175000017500000000276014245105073016103 0ustar apmapm{ "abstract" : "Passphrases and Passwords as objects for Dancer2", "author" : [ "Henk van Oers " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.64, CPAN::Meta::Converter version 2.150010", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "Dancer2-Plugin-Passphrase", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "Crypt::Bcrypt" : "0.006", "Dancer2" : "0.200000", "Data::Entropy" : "0.007", "Digest::Bcrypt" : "1.212", "Digest::SHA" : "5.74", "Test::More" : "0", "perl" : "5.008001" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "web" : "https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/issues" }, "homepage" : "https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/", "repository" : { "url" : "https://github.com/PerlDancer/Dancer2-Plugin-Passphrase" } }, "version" : "v3.4.1", "x_serialization_backend" : "JSON::PP version 2.27400_02" } Dancer2-Plugin-Passphrase-3.4.1/Makefile.PL0000644000175000017500000000215614245104416016433 0ustar apmapmuse strict; use warnings FATAL => 'all'; use ExtUtils::MakeMaker; WriteMakefile( NAME => 'Dancer2::Plugin::Passphrase', AUTHOR => q{Henk van Oers }, VERSION_FROM => 'lib/Dancer2/Plugin/Passphrase.pm', ABSTRACT_FROM => 'lib/Dancer2/Plugin/Passphrase.pm', ($ExtUtils::MakeMaker::VERSION >= 6.48 ? ('LICENSE'=> 'perl') : ()), MIN_PERL_VERSION => 5.008001, PL_FILES => {}, PREREQ_PM => { 'Test::More' => 0, 'Crypt::Bcrypt' => '0.006', 'Dancer2' => '0.200000', 'Digest::Bcrypt' => '1.212', 'Digest::SHA' => 5.74, 'Data::Entropy' => 0.007, }, dist => { COMPRESS => 'gzip -9f', SUFFIX => 'gz', }, clean => { FILES => 'Dancer2-Plugin-Passphrase-*' }, META_MERGE => { resources => { repository => 'https://github.com/PerlDancer/Dancer2-Plugin-Passphrase', bugtracker => 'https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/issues', homepage => 'https://github.com/PerlDancer/Dancer2-Plugin-Passphrase/', }, }, ); Dancer2-Plugin-Passphrase-3.4.1/lib/0000755000175000017500000000000014245105073015223 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/0000755000175000017500000000000014245105073016501 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/Plugin/0000755000175000017500000000000014245105073017737 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/Plugin/Passphrase/0000755000175000017500000000000014245105073022050 5ustar apmapmDancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/Plugin/Passphrase/Hashed.pm0000644000175000017500000000277412642460450023616 0ustar apmapmpackage Dancer2::Plugin::Passphrase::Hashed; use strict; use warnings; use MIME::Base64 qw(encode_base64); # ABSTRACT: Passphrases and Passwords as objects for Dancer2 =head1 NAME Dancer2::Plugin::Passphrase::Hashed - Helper package for Dancer2::Plugin::Passphrase. =head1 METHODS =head2 rfc2307() =head2 scheme() =head2 algorithm() =head2 cost() =head2 plaintext() =head2 salt_raw() =head2 hash_raw() =head2 salt_hex() =head2 hash_hex() =head2 salt_base64() =head2 hash_base64() =head1 AUTHOR Maintainer: Henk van Oers =head1 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. =cut sub new { my $class = shift; my @args = @_; return bless { @args == 1 ? %{$args[0]} : @args }, $class; } sub rfc2307 { $_[0]->{'rfc2307'} || undef } sub scheme { $_[0]->{'scheme'} || undef } sub algorithm { $_[0]->{'algorithm'} || undef } sub cost { $_[0]->{'cost'} || undef } sub plaintext { $_[0]->{'plaintext'} || undef } sub salt_raw { $_[0]->{'salt'} || undef } sub hash_raw { $_[0]->{'hash'} || undef } sub salt_hex { unpack 'H*', $_[0]->{'salt'} } sub hash_hex { unpack 'H*', $_[0]->{'hash'} } sub salt_base64 { encode_base64( $_[0]->{'salt'}, '' ) } sub hash_base64 { encode_base64( $_[0]->{'hash'}, '' ) } 1; Dancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/Plugin/Passphrase/Core.pm0000644000175000017500000001477414245104405023311 0ustar apmapmpackage Dancer2::Plugin::Passphrase::Core; use strict; use warnings; use Carp qw(croak); use Digest; use MIME::Base64 qw(decode_base64 encode_base64); use Data::Entropy::Algorithms qw(rand_bits rand_int); # ABSTRACT: Passphrases and Passwords as objects for Dancer2 =head1 NAME Dancer2::Plugin::Passphrase::Core - Core package for Dancer2::Plugin::Passphrase. =head1 DESCRIPTION B =head1 AUTHOR Maintainer: Henk van Oers =head1 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. =cut sub new { my $class = shift; my @args = @_; return bless { @args == 1 ? %{$args[0]} : @args }, $class; } # { algorithm => '...', this => '...' } sub _merge_options { my $self = shift; my $options = shift; my $algorithm = $self->{'algorithm'}; my $settings = {}; # if we got options if ($options) { $algorithm = delete $options->{'algorithm'}; $settings = defined $options->{$algorithm} ? $options->{$algorithm} : $self->{$algorithm}; } # Specify empty string to get an unsalted hash # Leaving it undefs results in 128 random bits being used as salt # bcrypt requires this amount, and is reasonable for other algorithms $settings->{'salt'} = rand_bits(128) unless defined $settings->{'salt'}; # RFC 2307 scheme is based on the algorithm, with a prefixed 'S' for salted $settings->{'scheme'} = join '', $algorithm =~ /[\w]+/g; $settings->{'scheme'} = 'S'. $settings->{'scheme'} if $settings->{'salt'}; if ( $settings->{'scheme'} eq 'SHA1' ) { $settings->{'scheme'} = 'SHA'; } elsif ( $settings->{'scheme'} eq 'SSHA1' ) { $settings->{'scheme'} = 'SSHA'; } # Bcrypt requires a cost parameter if ( $algorithm eq 'Bcrypt' ) { $settings->{'scheme'} = 'CRYPT'; $settings->{'type'} = '2a'; $settings->{'cost'} //= $self->{'Bcrypt'}{'cost'} || 4; $settings->{'cost'} = 31 if $settings->{'cost'} > 31; $settings->{'cost'} = sprintf '%02d', $settings->{'cost'}; } $settings->{'algorithm'} = $algorithm; $settings->{'plaintext'} = $self->{'plaintext'}; return $settings; } # From Crypt::Eksblowfish::Bcrypt. # Bcrypt uses it's own variation on base64 sub _en_bcrypt_base64 { my ($octets) = @_; my $text = encode_base64($octets, ''); $text =~ tr{A-Za-z0-9+/=}{./A-Za-z0-9}d; return $text; } # And the decoder of bcrypt's custom base64 sub _de_bcrypt_base64 { my ($text) = @_; $text =~ tr{./A-Za-z0-9}{A-Za-z0-9+/}; $text .= "=" x (3 - (length($text) + 3) % 4); return decode_base64($text); } # Extracts the settings from an RFC 2307 string sub _extract_settings { my ($self, $rfc2307_string) = @_; my $settings = {}; my ($scheme, $rfc_settings) = ($rfc2307_string =~ m/^{(\w+)}(.*)/s); unless ($scheme && $rfc_settings) { croak "An RFC 2307 compliant string must be passed to matches()"; } if ($scheme eq 'CRYPT') { if ($rfc_settings =~ m/^\$2(?:a|x|y)\$/) { $scheme = 'Bcrypt'; $rfc_settings =~ m{\A\$(2a|2x|2y)\$([0-9]{2})\$([./A-Za-z0-9]{22})}x; @{$settings}{qw} = ( $1, $2, _de_bcrypt_base64($3) ); } else { croak "Unknown CRYPT format"; } } my $scheme_meta = { 'MD5' => { algorithm => 'MD5', octets => 128 / 8 }, 'SMD5' => { algorithm => 'MD5', octets => 128 / 8 }, 'SHA' => { algorithm => 'SHA-1', octets => 160 / 8 }, 'SSHA' => { algorithm => 'SHA-1', octets => 160 / 8 }, 'SHA224' => { algorithm => 'SHA-224', octets => 224 / 8 }, 'SSHA224' => { algorithm => 'SHA-224', octets => 224 / 8 }, 'SHA256' => { algorithm => 'SHA-256', octets => 256 / 8 }, 'SSHA256' => { algorithm => 'SHA-256', octets => 256 / 8 }, 'SHA384' => { algorithm => 'SHA-384', octets => 384 / 8 }, 'SSHA384' => { algorithm => 'SHA-384', octets => 384 / 8 }, 'SHA512' => { algorithm => 'SHA-512', octets => 512 / 8 }, 'SSHA512' => { algorithm => 'SHA-512', octets => 512 / 8 }, 'Bcrypt' => { algorithm => 'Bcrypt', octets => 128 / 8 }, }; $settings->{'scheme'} = $scheme; $settings->{'algorithm'} = $scheme_meta->{$scheme}{algorithm}; $settings->{'plaintext'} = $self->{'plaintext'};; if ( !defined $settings->{'salt'} ) { $settings->{'salt'} = substr( decode_base64($rfc_settings), $scheme_meta->{$scheme}{octets}, ); } return $settings; } sub _calculate_hash { my ( $self, $settings ) = @_; my $hasher = Digest->new( $settings->{'algorithm'} ); my ( $hash, $rfc2307 ); if ( $settings->{'algorithm'} eq 'Bcrypt' ) { $hasher->add( $settings->{'plaintext'} ); $hasher->salt( $settings->{'salt'} ); $hasher->cost( $settings->{'cost'} ); $hash = $hasher->digest; $rfc2307 = '{CRYPT}$' . $settings->{'type'} . '$' . $settings->{'cost'} . '$' . _en_bcrypt_base64( $settings->{'salt'} ) . _en_bcrypt_base64($hash); } else { $hasher->add( $settings->{'plaintext'} ); $hasher->add( $settings->{'salt'} ); $hash = $hasher->digest; $rfc2307 = '{' . $settings->{'scheme'} . '}' . encode_base64( $hash . $settings->{'salt'}, '' ); } return Dancer2::Plugin::Passphrase::Hashed->new( hash => $hash, rfc2307 => $rfc2307, %{$settings}, ); } sub generate { my $self = shift; my $options = shift; my $settings = $self->_merge_options($options); return $self->_calculate_hash($settings); } sub generate_random { my ($self, $options) = @_; # Default is 16 URL-safe base64 chars. Supported everywhere and a reasonable length my $length = $options->{length} || 16; my $charset = $options->{charset} || ['a'..'z', 'A'..'Z', '0'..'9', '-', '_']; return join '', map { @$charset[rand_int scalar @$charset] } 1..$length; } sub matches { my ($self, $stored_hash) = @_; my $settings = $self->_extract_settings($stored_hash); my $new_hash = $self->_calculate_hash($settings)->rfc2307; return ($new_hash eq $stored_hash) ? 1 : undef; } 1; Dancer2-Plugin-Passphrase-3.4.1/lib/Dancer2/Plugin/Passphrase.pm0000644000175000017500000003726314245104613022420 0ustar apmapmpackage Dancer2::Plugin::Passphrase; use strict; use warnings; use Dancer2::Plugin::Passphrase::Core; use Dancer2::Plugin::Passphrase::Hashed; use Dancer2::Plugin; our $VERSION = '3.4.1'; plugin_keywords 'passphrase'; # ABSTRACT: Passphrases and Passwords as objects for Dancer2 =head1 NAME Dancer2::Plugin::Passphrase - Passphrases and Passwords as objects for Dancer2 =head1 DEPRECATION WARNING B This module is DEPRECATED, and it is advised that you switch to L if possible. =head1 SYNOPSIS This plugin manages the hashing of passwords for Dancer2 apps, allowing developers to follow cryptography best practices without having to become a cryptography expert. It uses the bcrypt algorithm as the default, while also supporting any hashing function provided by L. =head1 USAGE package MyWebService; use Dancer2; use Dancer2::Plugin::Passphrase; post '/login' => sub { my $phrase = passphrase( param('my password') )->generate; # $phrase is now an object that contains RFC 2307 representation # of the hashed passphrase, along with the salt, and other metadata # You should store $phrase->rfc2307() for use later }; get '/protected' => sub { # Retrieve $stored_rfc_2307_string, like we created above. # IT MUST be a valid RFC 2307 string if ( passphrase( param('my password') )->matches( $stored_rfc_2307 ) ) { # Passphrase matches! } }; get '/generate_new_password' => sub { return passphrase->generate_random; }; =head1 NOTE This package does no checking about how secure the password is, minimum length or anything, including a length of 0 being valid. You can add extra checks in your "MyWebService". =head1 AUTO STRINGIFICATION IS REMOVED You must use $phrase->rfc2307() to get a text string. =head1 KEYWORDS =head2 passphrase Given a plaintext password, it returns a Dancer2::Plugin::Passphrase::Core object that you can generate a new hash from, or match against a stored hash. =cut has algorithm => ( is => 'ro', from_config => sub { 'Bcrypt' }, ); sub passphrase { my ($plugin, $plaintext) = @_; return Dancer2::Plugin::Passphrase::Core->new( %{$plugin->config}, algorithm => $plugin->algorithm, plaintext => $plaintext, ); } 1; __END__ =head1 MAIN METHODS =head2 generate Generates an RFC 2307 representation of the hashed passphrase that is suitable for storage in a database. my $phrase = passphrase('my passphrase')->generate; It returns a Dancer2::Plugin::Passphrase::Hashed object. You should store C<< $phrase->rfc_2307() >> in your database. Accepts a hashref of options to specify what kind of hash should be generated. All options settable in the config file are valid. If you specify only the algorithm, the default settings for that algorithm will be used. A cryptographically random salt is used if salt is not defined. Only if you specify the empty string will an empty salt be used. This is not recommended, and should only be used to upgrade old insecure hashes. my $phrase = passphrase('my password')->generate( { algorithm => $algo_name, # override algo from config $algo_name => { # override options for this algorithm $opt1 => $value1, }, } ); So for Bcrypt this might be: my $phrase = passphrase('my password')->generate( { algorithm => 'Bcrypt', Bcrypt => { cost => 14, } } ); =head2 matches Matches a plaintext password against a stored hash. Returns 1 if the hash of the password matches the stored hash. Returns undef if they don't match or if there was an error Fail-Secure, rather than Fail-Safe. passphrase('my password')->matches($stored_rfc_2307_string); $stored_rfc_2307_string B be a valid RFC 2307 string, as created by L An RFC 2307 string is made up of a scheme identifier, followed by a base64 encoded string. The base64 encoded string should contain the password hash and the salt concatenated together - in that order. '{'.$scheme.'}'.encode_base64($hash . $salt, ''); Where C<$scheme> can be any of the following and their unsalted variants, which have the leading S removed. CRYPT will be Bcrypt. SMD5 SSHA SSHA224 SSHA256 SSHA384 SSHA512 CRYPT A complete RFC2307 string looks like this: {SSHA}K3LAbIjRL5CpLzOlm3/HzS3qt/hUaGVTYWx0 This is the format created by L =head2 generate_random Generates and returns any number of cryptographically random characters from the url-safe base64 character set. my $rand_pass = passphrase->generate_random; The passwords generated are suitable for use as temporary passwords or one-time authentication tokens. You can configure the length and the character set used by passing a hashref of options. my $rand_pass = passphrase->generate_random({ length => 32, charset => ['a'..'z', 'A'..'Z'], }); =head1 ADDITIONAL METHODS The methods are only applicable once you have called C passphrase( 'my password' )->generate->rfc2307; # CORRECT passphrase( 'my password' )->rfc2307; # INCORRECT, Returns undef =head2 rfc2307 Returns the rfc2307 representation from a C object. passphrase('my password')->generate->rfc2307; =head2 scheme Returns the scheme name from a C object. This is the scheme name as used in the RFC 2307 representation passphrase('my password')->generate->scheme; The scheme name can be any of the following, and will always be capitalized SMD5 SSHA SSHA224 SSHA256 SSHA384 SSHA512 CRYPT MD5 SHA SHA224 SHA256 SHA384 SHA512 =head2 algorithm Returns the algorithm name from a C object. The algorithm name can be anything that is accepted by C<< Digest->new($alg) >> This includes any modules in the C Namespace passphrase('my password')->generate->algorithm; =head2 cost Returns the bcrypt cost from a C object. Only works when using the bcrypt algorithm, returns undef for other algorithms passphrase('my password')->generate->cost; =head2 salt_raw Returns the raw salt from a C object. passphrase('my password')->generate->salt_raw; Can be defined, but false - The empty string is technically a valid salt. Returns C if there is no salt. =head2 hash_raw Returns the raw hash from a C object. passphrase('my password')->generate->hash_raw; =head2 salt_hex Returns the hex-encoded salt from a C object. Can be defined, but false - The empty string is technically a valid salt. Returns C if there is no salt. passphrase('my password')->generate->salt_hex; =head2 hash_hex Returns the hex-encoded hash from a C object. passphrase('my password')->generate->hash_hex; =head2 salt_base64 Returns the base64 encoded salt from a C object. Can be defined, but false - The empty string is technically a valid salt. Returns C if there is no salt. passphrase('my password')->generate->salt_base64; =head2 hash_base64 Returns the base64 encoded hash from a C object. passphrase('my password')->generate->hash_base64; =head2 plaintext Returns the plaintext password as originally supplied to the L keyword. passphrase('my password')->generate->plaintext; =head1 MORE INFORMATION =head2 Purpose The aim of this module is to help you store new passwords in a secure manner, whilst still being able to verify and upgrade older passwords. Cryptography is a vast and complex field. Many people try to roll their own methods for securing user data, but succeed only in coming up with a system that has little real security. This plugin provides a simple way of managing that complexity, allowing developers to follow crypto best practice without having to become an expert. =head2 Rationale The module defaults to hashing passwords using the bcrypt algorithm, returning them in RFC 2307 format. RFC 2307 describes an encoding system for passphrase hashes, as used in the "userPassword" attribute in LDAP databases. It encodes hashes as ASCII text, and supports several passphrase schemes by starting the encoding with an alphanumeric scheme identifier enclosed in braces. RFC 2307 only specifies the C, and C schemes - however in real-world usage, schemes that are salted are widely supported, and are thus provided by this module. Bcrypt is an adaptive hashing algorithm that is designed to resist brute force attacks by including a cost (aka work factor). This cost increases the computational effort it takes to compute the hash. SHA and MD5 are designed to be fast, and modern machines compute a billion hashes a second. With computers getting faster every day, brute forcing SHA hashes is a very real problem that cannot be easily solved. Increasing the cost of generating a bcrypt hash is a trivial way to make brute forcing ineffective. With a low cost setting, bcrypt is just as secure as a more traditional SHA+salt scheme, and just as fast. Increasing the cost as computers become more powerful keeps you one step ahead For a more detailed description of why bcrypt is preferred, see this article: L =head2 Configuration In your applications config file, you can set the default hashing algorithm, and the default settings for every supported algorithm. Calls to L will use the default settings for that algorithm specified in here. You can override these defaults when you call L. If you do no configuration at all, the default is to bcrypt with a cost of 4, and a strong psuedo-random salt. plugins: Passphrase: algorithm: Bcrypt cost: 8 =head2 Storage in a database You should be storing the RFC 2307 string in your database, it's the easiest way to use this module. You could store the C, C, and C separately, but this strongly discouraged. RFC 2307 strings are specifically designed for storing hashed passwords, and should be used wherever possible. The length of the string produced by L can vary dependent on your settings. Below is a table of the lengths generated using default settings. You will need to make sure your database columns are at least this long. If the string gets truncated, the password can I be validated. ALGORITHM LENGTH EXAMPLE RFC 2307 STRING Bcrypt 67 {CRYPT}$2a$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS SHA-512 117 {SSHA512}lZG4dZ5EU6dPEbJ1kBPPzEcupFloFSIJjiXCwMVxJXOy/x5qhBA5XH8FiUWj7u59onQxa97xYdqje/fwY5TDUcW1Urplf3KHMo9NO8KO47o= SHA-384 97 {SSHA384}SqZF5YYyk4NdjIM8YgQVfRieXDxNG0dKH4XBcM40Eblm+ribCzdyf0JV7i2xJvVHZsFSQNcuZPKtiTMzDyOU+w== SHA-256 73 {SSHA256}xsJHNzPlNCpOZ41OkTfQOU35ZY+nRyZFaM8lHg5U2pc0xT3DKNlGW2UTY0NPYsxU SHA-224 69 {SSHA224}FTHNkvKOdyX1d6f45iKLVxpaXZiHel8pfilUT1dIZ5u+WIUyhDGxLnx72X0= SHA-1 54 {SSHA}Qsaao/Xi/bYTRMQnpHuD3y5nj02wbdcw5Cek2y2nLs3pIlPh MD5 50 {SMD5}bgfLiUQWgzUm36+nBhFx62bi0xdwTp+UpEeNKDxSLfM= =head2 Common Mistakes Common mistakes people make when creating their own solution. If any of these seem familiar, you should probably be using this module =over =item Passwords are stored as plain text for a reason There is never a valid reason to store a password as plain text. Passwords should be reset and not emailed to customers when they forget. Support people should be able to login as a user without knowing the users password. No-one except the user should know the password - that is the point of authentication. =item No-one will ever guess our super secret algorithm! Unless you're a cryptography expert with many years spent studying super-complex maths, your algorithm is almost certainly not as secure as you think. Just because it's hard for you to break doesn't mean it's difficult for a computer. =item Our application-wide salt is "Sup3r_S3cret_L0ng_Word" - No-one will ever guess that. This is common misunderstanding of what a salt is meant to do. The purpose of a salt is to make sure the same password doesn't always generate the same hash. A fresh salt needs to be created each time you hash a password. It isn't meant to be a secret key. =item We generate our random salt using C. C isn't actually random, it's a non-unform pseudo-random number generator, and not suitable for cryptographic applications. Whilst this module also defaults to a PRNG, it is better than the one provided by C. Using a true RNG is a config option away, but is not the default as it it could potentially block output if the system does not have enough entropy to generate a truly random number =item We use C, and the salt is from C MD5 has been broken for many years. Commodity hardware can find a hash collision in seconds, meaning an attacker can easily generate the correct MD5 hash without using the correct password. =item We use C, and the salt is from C SHA isn't quite as broken as MD5, but it shares the same theoretical weaknesses. Even without hash collisions, it is vulnerable to brute forcing. Modern hardware is so powerful it can try around a billion hashes a second. That means every 7 character password in the range [A-Za-z0-9] can be cracked in one hour on your average desktop computer. =item If the only way to break the hash is to brute-force it, it's secure enough It is unlikely that your database will be hacked and your hashes brute forced. However, in the event that it does happen, or SHA512 is broken, using this module gives you an easy way to change to a different algorithm, while still allowing you to validate old passphrases =back =head1 KNOWN ISSUES If you see errors like this Wide character in subroutine entry or Input must contain only octets The C, C, and C algorithms can't handle characters with an ordinal value above 255, producing errors like this if they encounter them. It is not possible for this plugin to automagically work out the correct encoding for a given string. If you see errors like this, then you probably need to use the L module to encode your text as UTF-8 (or whatever encoding it is) before giving it to C. Text encoding is a bag of hurt, and errors like this are probably indicitive of deeper problems within your app's code. You will save yourself a lot of trouble if you read up on the L module sooner rather than later. For further reading on UTF-8, unicode, and text encoding in perl, see L =head1 SEE ALSO L, L, L =head1 ACKNOWLEDGMENTS =over =item James Aitken for his D1 version. =item Sawyer X for his D2 magic. =item Mohammad S Anwar (GH#4, typo fixes) =item Jim Davis (GH#5) =item Peter Mottram (GH#11) =item Nuno Carvalho (GH#12) =item Tom Adams (fix generate docs) =item Jeremi M. Gosney (GH #2) =item Sergiy Borodych (GH #3) =back =head1 COPYRIGHT AND LICENSE Copyright (c) 2016-2018 Peter Mottram . Copyright (c) 2016 Henk van Oers . Copyright (c) 2012-2016 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. =cut