view release on metacpan or  search on metacpan

lib/Apache2/API/Password.pod  view on Meta::CPAN

    my $c = $ht->bcrypt_cost;

Sets or gets the bcrypt cost factor (4–31). Default is 12. Higher values increase security but slow computation. Note: Apache's C<htpasswd -B> caps at 17; this module supports 4..31.

=head2 create

    $ht->create(1);
    my $bool = $ht->create;

Boolean flag indicating whether the constructor should create a new hash from the provided cleartext. Typically passed to C<new>.

=head2 hash

    my $hash = $ht->hash;
    # validate & set; also updates 'salt'
    $ht->hash( $crypt_hash );

Gets or sets the stored hash (e.g.: C<$apr1$>). Setting validates format and extracts metadata, such as C<salt>.

=head2 salt

    my $salt = $ht->salt;
    $ht->salt( 'abcd1234' );

Gets or sets the salt (1–8 chars in C<[./0-9A-Za-z]> for C<MD5>, 22 chars for C<bcrypt>, 1–16 chars for C<SHA-256/512>, alphabet C<[./0-9A-Za-z]>).

If an hash is provided upon object construction, its C<salt> will be derived, and stored.

=head2 sha_rounds

    $ht->sha_rounds(150000);
    my $r = $ht->sha_rounds;

Sets or gets the number of rounds for C<SHA-256/512> (1000–999999999). Default is 5000.

=head2 make

    my $hash = $ht->make( $clear_password );
    my $hash = $ht->make( $clear_password, $salt );

Generates a hash using the selected L<algorithm|/algo>. If C<$salt> is omitted, the value stored in L</salt> is used or a random C<salt> is generated. The C<salt> is clamped to the valid alphabet and truncated to the appropriate number of characters ...

Returns the generated hash on success, or, upon error, C<undef> in scalar context, or an empty list in list context.

=head2 make_md5

    my $hash = $ht->make_md5( $clear_password, $salt );

Generates an APR1 MD5 hash (C<$apr1$<salt>$<hash>). Salt is 1–8 chars, default random.

=head2 make_bcrypt

    my $hash = $ht->make_bcrypt( $clear_password, $salt );

Generates a bcrypt hash (C<$2y$<cost>$<salt-and-hash>). Salt is 22 chars, default random. Uses C<bcrypt_cost>.

=head2 make_sha256

    my $hash = $ht->make_sha256( $clear_password, $salt );

Generates a SHA-256 crypt hash (C<$5$[rounds=<n>$]<salt>$<hash>). Salt is 1–16 chars, default random. Uses C<sha_rounds>.

=head2 make_sha512

    my $hash = $ht->make_sha512( $clear_password, $salt );

Generates a SHA-512 crypt hash (C<$6$[rounds=<n>$]<salt>$<hash>). Salt is 1–16 chars, default random. Uses C<sha_rounds>.

=head2 matches

    my $ok = $ht->matches( $user_input_password );

Compute a fresh hash using the instance salt and compare with the stored L<hash|/hash>.

Returns true if the cleartext password matches.

=head1 EXAMPLES

=head2 Creating a C<.htpasswd> line

    my $user = 'john';
    my $ht   = Apache2::API::Password->new( 's3cret', create => 1 );
    say join( ':', $user, $ht->hash );

=head2 Verifying a login

    my $stored = '$apr1$hfT7jp2q$DcU1Hf5w2Q/9G8yqv1hbl.';
    my $ht     = Apache2::API::Password->new( $stored );
    if( $ht->matches( $input_password ) )
    {
        # ok
    }

=head1 THREAD SAFETY

This module keeps per-object state only (C<algo>, C<salt>, C<bcrypt_cost>, C<sha_rounds>, C<hash>) and uses no mutable global variables except precompiled regex constants. As such, it is I<re-entrant> and safe to use from multiple Perl L<ithreads|per...

For bcrypt/SHA-crypt, verification/generation prefers the system C<crypt(3)>; on modern libcs this is thread-safe. When the system lacks support, fallbacks are used:

=over 4

=item * L<Authen::Passphrase::BlowfishCrypt>, L<Crypt::Bcrypt>, L<Crypt::Eksblowfish::Bcrypt> (bcrypt)

=item * L<Crypt::Passwd::XS> (bcrypt and SHA-crypt)

=back

These libraries are widely used and do not expose shared mutable globals for the operations performed here; there are no known thread-safety issues in typical Perl ithread usage. If your deployment uses C<fork> rather than ithreads, objects are indep...

=head1 COMPATIBILITY

=over 4

=item * APR1 output is identical to C<htpasswd -m> and L<Crypt::PasswdMD5/apache_md5_crypt>.

=item * bcrypt output is compatible with C<htpasswd -B> (C<$2y$...>).

=item * SHA-crypt output is compatible with C<htpasswd -2> (C<$5$>) and C<-5> (C<$6$>).

=back

All 64 encoding symbols (including trailing C<.> or C</>) are valid.

=head1 SECURITY NOTES

=over 4