.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Digest::Bcrypt 3pm"
.TH Digest::Bcrypt 3pm "2022-01-22" "perl v5.32.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Digest::Bcrypt \- Perl interface to the bcrypt digest algorithm
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 5
\&    #!/usr/bin/env perl
\&    use strict;
\&    use warnings;
\&    use utf8;
\&    use Digest;   # via the Digest module (recommended)
\&
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, cost => 12, salt => \*(Aqabcdefgh♥stuff\*(Aq);
\&    # You can forego the cost and salt in favor of settings strings:
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, settings => \*(Aq$2a$20$GA.eY03tb02ea0DqbA.eG.\*(Aq);
\&
\&    # $cost is an integer between 5 and 31
\&    $bcrypt\->cost(12);
\&
\&    # $type is a selection between 2a, 2b, 2x, and 2y
\&    $bcrypt\->type(\*(Aq2b\*(Aq);
\&
\&    # $salt must be exactly 16 octets long
\&    $bcrypt\->salt(\*(Aqabcdefgh♥stuff\*(Aq);
\&    # OR, for good, random salts:
\&    use Data::Entropy::Algorithms qw(rand_bits);
\&    $bcrypt\->salt(rand_bits(16*8)); # 16 octets
\&
\&    # You can forego the cost and salt in favor of settings strings:
\&    $bcrypt\->settings(\*(Aq$2a$20$GA.eY03tb02ea0DqbA.eG.\*(Aq);
\&
\&    # add some strings we want to make a secret of
\&    $bcrypt\->add(\*(Aqsome stuff\*(Aq, \*(Aqhere and\*(Aq, \*(Aqhere\*(Aq);
\&
\&    my $digest = $bcrypt\->digest;
\&    $digest = $bcrypt\->hexdigest;
\&    $digest = $bcrypt\->b64digest;
\&
\&    # bcrypt\*(Aqs own non\-standard base64 dictionary
\&    $digest = $bcrypt\->bcrypt_b64digest;
\&
\&    # Now, let\*(Aqs create a password hash and check it later:
\&    use Data::Entropy::Algorithms qw(rand_bits);
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, type => \*(Aq2b\*(Aq, cost => 20, salt => rand_bits(16*8));
\&    my $settings = $bcrypt\->settings(); # save for later checks.
\&    my $pass_hash = $bcrypt\->add(\*(AqSome secret password\*(Aq)\->digest;
\&
\&    # much later, we can check a password against our hash via:
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, settings => $settings);
\&    if ($bcrypt\->add($value_from_user)\->digest eq $known_pass_hash) {
\&        say "Your password matched";
\&    }
\&    else {
\&        say "Try again!";
\&    }
\&
\&    # Now that you\*(Aqve seen how cumbersome/silly that is,
\&    # please use Crypt::Bcrypt instead of this module.
.Ve
.SH "NOTICE"
.IX Header "NOTICE"
While maintenance for Digest::Bcrypt will continue, there's no reason to use
Digest::Bcrypt when Crypt::Bcrypt already exists.  We strongly suggest
that you use Crypt::Bcrypt instead.
.PP
This \f(CW\*(C`Digest::Bcrypt\*(C'\fR interface is crufty and laborious to use when compared
to that of Crypt::Bcrypt.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Digest::Bcrypt provides a Digest\-based interface to the
Crypt::Bcrypt library.
.PP
Please note that you \fBmust\fR set a \f(CW\*(C`salt\*(C'\fR of exactly 16 octets in length,
and you \fBmust\fR provide a \f(CW\*(C`cost\*(C'\fR in the range \f(CW1..31\fR.
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
Digest::Bcrypt implements the following attributes.
.SS "cost"
.IX Subsection "cost"
.Vb 2
\&    $bcrypt = $bcrypt\->cost(20); # allows for method chaining
\&    my $cost = $bcrypt\->cost();
.Ve
.PP
An integer in the range \f(CW5..31\fR, this is required.
.PP
See Crypt::Eksblowfish::Bcrypt for a detailed description of \f(CW\*(C`cost\*(C'\fR
in the context of the bcrypt algorithm.
.PP
When called with no arguments, it will return the current cost.
.SS "salt"
.IX Subsection "salt"
.Vb 2
\&    $bcrypt = $bcrypt\->salt(\*(Aqabcdefgh♥stuff\*(Aq); # allows for method chaining
\&    my $salt = $bcrypt\->salt();
\&
\&    # OR, for good, random salts:
\&    use Data::Entropy::Algorithms qw(rand_bits);
\&    $bcrypt\->salt(rand_bits(16*8)); # 16 octets
.Ve
.PP
Sets the value to be used as a salt. Bcrypt requires \fBexactly\fR 16 octets of salt.
.PP
It is recommenced that you use a module like Data::Entropy::Algorithms to
provide a truly randomized salt.
.PP
When called with no arguments, it will return the current salt.
.SS "settings"
.IX Subsection "settings"
.Vb 2
\&    $bcrypt = $bcrypt\->settings(\*(Aq$2a$20$GA.eY03tb02ea0DqbA.eG.\*(Aq); # allows for method chaining
\&    my $settings = $bcrypt\->settings();
.Ve
.PP
A \f(CW\*(C`settings\*(C'\fR string can be used to set the \*(L"salt\*(R" in Digest::Bcrypt and
\&\*(L"cost\*(R" in Digest::Bcrypt automatically. Setting the \f(CW\*(C`settings\*(C'\fR will override any
current values in your \f(CW\*(C`cost\*(C'\fR and \f(CW\*(C`salt\*(C'\fR attributes.
.PP
For details on the \f(CW\*(C`settings\*(C'\fR string requirements, please see Crypt::Eksblowfish::Bcrypt.
.PP
When called with no arguments, it will return the current settings string.
.SS "type"
.IX Subsection "type"
.Vb 3
\&    $bcrypt = $bcrypt\->type(\*(Aq2b\*(Aq);
\&    # method chaining on mutations
\&    say $bcrypt\->type(); # 2b
.Ve
.PP
This sets the subtype of bcrypt used. These subtypes are as defined in Crypt::Bcrypt.
The available types are:
\&\f(CW\*(C`2b\*(C'\fR which is the current standard,
\&\f(CW\*(C`2a\*(C'\fR which is older; it's the one used in Crypt::Eksblowfish,
\&\f(CW\*(C`2y\*(C'\fR which is considered equivalent to \f(CW\*(C`2b\*(C'\fR and used in \s-1PHP.\s0
\&\f(CW\*(C`2x\*(C'\fR which is very broken and only needed to work with ancient \s-1PHP\s0 versions.
.SH "METHODS"
.IX Header "METHODS"
Digest::Bcrypt inherits all methods from Digest::base and implements/overrides
the following methods as well.
.SS "new"
.IX Subsection "new"
.Vb 4
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, %params);
\&    my $bcrypt = Digest::Bcrypt\->new(%params);
\&    my $bcrypt = Digest\->new(\*(AqBcrypt\*(Aq, \e%params);
\&    my $bcrypt = Digest::Bcrypt\->new(\e%params);
.Ve
.PP
Creates a new \f(CW\*(C`Digest::Bcrypt\*(C'\fR object. It is recommended that you use the Digest
module in the first example rather than using Digest::Bcrypt directly.
.PP
Any of the \*(L"\s-1ATTRIBUTES\*(R"\s0 in Digest::Bcrypt above can be passed in as a parameter.
.SS "add"
.IX Subsection "add"
.Vb 4
\&    $bcrypt\->add("a"); $bcrypt\->add("b"); $bcrypt\->add("c");
\&    $bcrypt\->add("a")\->add("b")\->add("c");
\&    $bcrypt\->add("a", "b", "c");
\&    $bcrypt\->add("abc");
.Ve
.PP
Adds data to the message we are calculating the digest for. All the above
examples have the same effect.
.SS "b64digest"
.IX Subsection "b64digest"
.Vb 1
\&    my $digest = $bcrypt\->b64digest;
.Ve
.PP
Same as \*(L"digest\*(R", but will return the digest base64 encoded.
.PP
The \f(CW\*(C`length\*(C'\fR of the returned string will be 31 and will only contain characters
from the ranges \f(CW\*(Aq0\*(Aq..\*(Aq9\*(Aq\fR, \f(CW\*(AqA\*(Aq..\*(AqZ\*(Aq\fR, \f(CW\*(Aqa\*(Aq..\*(Aqz\*(Aq\fR, \f(CW\*(Aq+\*(Aq\fR, and \f(CW\*(Aq/\*(Aq\fR
.PP
The base64 encoded string returned is not padded to be a multiple of 4 bytes long.
.SS "bcrypt_b64digest"
.IX Subsection "bcrypt_b64digest"
.Vb 1
\&    my $digest = $bcrypt\->bcrypt_b64digest;
.Ve
.PP
Same as \*(L"digest\*(R", but will return the digest base64 encoded using the alphabet
that is commonly used with bcrypt.
.PP
The \f(CW\*(C`length\*(C'\fR of the returned string will be 31 and will only contain characters
from the ranges \f(CW\*(Aq0\*(Aq..\*(Aq9\*(Aq\fR, \f(CW\*(AqA\*(Aq..\*(AqZ\*(Aq\fR, \f(CW\*(Aqa\*(Aq..\*(Aqz\*(Aq\fR, \f(CW\*(Aq+\*(Aq\fR, and \f(CW\*(Aq.\*(Aq\fR
.PP
The base64 encoded string returned is not padded to be a multiple of 4 bytes long.
.PP
\&\fINote:\fR This is bcrypt's own non-standard base64 alphabet, It is \fBnot\fR
compatible with the standard \s-1MIME\s0 base64 encoding.
.SS "clone"
.IX Subsection "clone"
.Vb 1
\&    my $clone = $bcrypt\->clone;
.Ve
.PP
Creates a clone of the \f(CW\*(C`Digest::Bcrypt\*(C'\fR object, and returns it.
.SS "digest"
.IX Subsection "digest"
.Vb 1
\&    my $digest = $bcrypt\->digest;
.Ve
.PP
Returns the binary digest for the message. The returned string will be 23 bytes long.
.SS "hexdigest"
.IX Subsection "hexdigest"
.Vb 1
\&    my $digest = $bcrypt\->hexdigest;
.Ve
.PP
Same as \*(L"digest\*(R", but will return the digest in hexadecimal form.
.PP
The \f(CW\*(C`length\*(C'\fR of the returned string will be 46 and will only contain
characters from the ranges \f(CW\*(Aq0\*(Aq..\*(Aq9\*(Aq\fR and \f(CW\*(Aqa\*(Aq..\*(Aqf\*(Aq\fR.
.SS "reset"
.IX Subsection "reset"
.Vb 1
\&    $bcrypt\->reset;
.Ve
.PP
Resets the object to the same internal state it was in when it was constructed.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Digest, Crypt::Eksblowfish::Bcrypt, Data::Entropy::Algorithms
.SH "AUTHOR"
.IX Header "AUTHOR"
James Aitken \f(CW\*(C`jaitken@cpan.org\*(C'\fR
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
.IP "\(bu" 4
Chase Whitener \f(CW\*(C`capoeira@cpan.org\*(C'\fR
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is copyright (c) 2012 by James Aitken.
.PP
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.