view release on metacpan or  search on metacpan

README  view on Meta::CPAN

You will need to make sure your database columns are at least this long.
If the string gets truncated, the password can _never_ be validated.

    ALGORITHM   LENGTH  EXAMPLE RFC 2307 STRING
    
    Bcrypt      68      {CRYPT}$2a$04$MjkMhQxasFQod1qq56DXCOvWu6YTWk9X.EZGnmSSIbbtyEBIAixbS
    SHA-512     118     {SSHA512}lZG4dZ5EU6dPEbJ1kBPPzEcupFloFSIJjiXCwMVxJXOy/x5qhBA5XH8FiUWj7u59onQxa97xYdqje/fwY5TDUcW1Urplf3KHMo9NO8KO47o=
    SHA-384     98      {SSHA384}SqZF5YYyk4NdjIM8YgQVfRieXDxNG0dKH4XBcM40Eblm+ribCzdyf0JV7i2xJvVHZsFSQNcuZPKtiTMzDyOU+w==
    SHA-256     74      {SSHA256}xsJHNzPlNCpOZ41OkTfQOU35ZY+nRyZFaM8lHg5U2pc0xT3DKNlGW2UTY0NPYsxU
    SHA-224     70      {SSHA224}FTHNkvKOdyX1d6f45iKLVxpaXZiHel8pfilUT1dIZ5u+WIUyhDGxLnx72X0=
    SHA-1       55      {SSHA}Qsaao/Xi/bYTRMQnpHuD3y5nj02wbdcw5Cek2y2nLs3pIlPh
    MD5         51      {SMD5}bgfLiUQWgzUm36+nBhFx62bi0xdwTp+UpEeNKDxSLfM=

## 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

# KNOWN ISSUES

If you see errors like this

    Wide character in subroutine entry

or

    Input must contain only octets

The `MD5`, `bcrypt`, and `SHA` algorithms can't handle chracters 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 [Encode](https://metacpan.org/pod/Encode) module
to encode your text as UTF-8 (or whatever encoding it is) before giving it 
to `passphrase`.

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
[Encode](https://metacpan.org/pod/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](http://training.perl.com/OSCON2011/index.html)

# SEE ALSO

[Dancer](https://metacpan.org/pod/Dancer), [Digest](https://metacpan.org/pod/Digest), [Crypt::Eksblowfish::Bcrypt](https://metacpan.org/pod/Crypt::Eksblowfish::Bcrypt), [Dancer::Plugin::Bcrypt](https://metacpan.org/pod/Dancer::Plugin::Bcrypt)

# AUTHOR

James Aitken <jaitken@cpan.org>

# 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.