James Aitken > Dancer-Plugin-Passphrase-1.0.0 > Dancer::Plugin::Passphrase



Annotate this POD

View/Report Bugs
Module Version: 1.0.0   Source   Latest Release: Dancer-Plugin-Passphrase-2.0.1




This plugin manages the hashing of passwords for Dancer apps, allowing developers to follow best cryptography practice without having to become a cryptography expert.

It uses the bcrypt algorithm as the default, wrapping Crypt::Eksblowfish::Bcrypt, and also supports any hashing function provided by Digest


    package MyWebService;
    use Dancer ':syntax';
    use Dancer::Plugin::Passphrase;

    post '/' sub => {
        my $hash = passphrase( param('password') )->generate_hash;

        # [...] Store $hash in DB

    get '/' sub => {
        # [...] Retrieve $stored_hash from the DB

        if ( passphrase( param('password') )->matches( $stored_hash ) ) {
            # Password matches!

    get '/generate_new_password' sub => {
        return passphrase->generate_random;






Generates and returns an RFC 2307 representation of the hashed passphrase that is suitable for storage in a database.

    my $hash = passphrase('my passphrase')->generate_hash;

You can pass a hashref of options to specify what kind of hash should be generated, all options you can set in the config file are valid.

If you specify only the package name, the default settings for that package from your config file will be used.


    my $hash = passphrase('my password')->generate_hash({
        scheme => '', # What method we'll use to hash



    passphrase('my password')->matches($stored_hash);

$stored_hash must be a valid RFC 2307 string 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.


Where $scheme can be any of the following and their salted variants, which are prefixed with an S.

    MD5 SHA SHA224 SHA256 SHA384 SHA512 CRYPT

Any algorithm that can be produced by a module conforming to the Digest spec will have it's own scheme, these are just the default ones

A complete RFC2307 string looks like this:


This module generates hashes in this format by default via generate_hash.



    my $rand_pass = passphrase->generate_random;



    my $rand_pass = passphrase->generate_random({
        length  => 32,



Returns the rfc2307 representation from a Dancer::Plugin::Passphrase object. Retu passphrase('password')->generate_hash->rfc2307;


Returns the scheme from a Dancer::Plugin::Passphrase object.
























Returns the plaintext password as originally supplied to the passphrase keyword.






This plugin provides a simple way of managing that complexity, allowing developers to follow best crypto practice without having to become a cryptography expert.

See the cookbook for some ideas on how to to move from older schemes.








For a more detailed description of why bcrypt is preferred, see this article: http://codahale.com/how-to-safely-store-a-password/

Common Mistakes


Passwords are stored as plain text for a reason


No-one will ever guess our super secret algorithm!




We generate our random salt using rand.









In your applications config file, you can set the default hashing algorithm, and the default settings for every supported algorithm. Calls to generate_hash will use the default settings for that algorithm specified in here.

You can override these defaults when you call generate_hash.


            default: bcrypt

                cost: 8




If you see errors like this

    Wide character in subroutine entry


    Input must contain only octets

The MD5 and bcrypt algorithms can't handle chracters with an ordinal value above 255, and produce 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.



You will probably save yourself a lot of hassle down the line if you read up on the Encode module sooner rather than later.

For further reading on UTF-8, unicode, and text encoding in perl, see http://training.perl.com/OSCON2011/index.html


James Aitken <jaitken@cpan.org>


This software is copyright (c) 2011 by James Aitken.


syntax highlighting: