view release on metacpan or  search on metacpan

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

=item * APR1 / MD5-crypt (C<$apr1$>) - same as C<htpasswd -m>

This implements the full APR1 algorithm (password + magic + salt, alternate sum, bit-mixing, 1000 rounds, and the crypt-style 64-symbol encoding) and is fully compatible with Apache’s C<htpasswd -m> and L<Crypt::PasswdMD5/ apache_md5_crypt>.

=item * bcrypt (C<$2y$>) - same as C<htpasswd -B>

Generated via the system C<crypt(3)> when available; otherwise falls back to C<Authen::Passphrase::BlowfishCrypt>, C<Crypt::Bcrypt>, or
C<Crypt::Eksblowfish::Bcrypt>.

=item * SHA-crypt (C<$5$ = SHA-256, $6$ = SHA-512>) - same as C<htpasswd -2> / C<-5>

Generated via the system C<crypt(3)> when available; otherwise falls back to C<Crypt::Passwd::XS>.

=back

This class handles existing Apache password or create new ones, and makes it possible to retrieve the encoded password, or to test if a user-provided clear password matches.

When constructing from an existing hash, the scheme is auto-detected by prefix (C<$apr1$>, C<$2y$>, C<$5$>, C<$6$>) and C<matches> uses the appropriate verifier.

=head2 CONSTRUCTOR

=head2 new

    my $ht = Apache2::API::Password->new( $clear, create => 1 );
    my $ht = Apache2::API::Password->new( $clear, create => 1, salt => $salt );
    my $ht = Apache2::API::Password->new( $apr1_hash );

    # Multi-algorithm creation:
    my $b  = Apache2::API::Password->new( $clear, create => 1, algo => 'bcrypt', bcrypt_cost => 12 );
    my $s5 = Apache2::API::Password->new( $clear, create => 1, algo => 'sha256', sha_rounds => 6000 );
    my $s6 = Apache2::API::Password->new( $clear, create => 1, algo => 'sha512', sha_rounds => 150000 );

This creates an instance either from:

=over 4

=item * a cleartext password (C<$clear>) with C<create =E<gt> 1>

Generates a new hash. If C<salt> is provided:

=over 8

=item * APR1: clamped to C<[./0-9A-Za-z]>, truncated to 8 chars.

=item * bcrypt: 22 chars in C<[./0-9A-Za-z]> (bcrypt base64).

=item * SHA-crypt: up to 16 chars in C<[./0-9A-Za-z]>.

=back

If omitted, a random salt is generated using L<Crypt::URandom> or L<Bytes::Random::Secure> (one of which must be installed).

=item * an existing modular-crypt hash string

E.g. the right-hand side of a C<.htpasswd> line: C<$apr1$...>, C<$2y$...>,
C<$5$...>, or C<$6$...>. The salt (and rounds/cost where applicable) are parsed.

=back

Note that the Apache algorithm to generate md5 password is not the same as simply using L<Digest::MD5>. Apache algorithm uses a more enhanced approach with a thousand iterations.

This constructor returns the newly instantiated object upon succes, or, upon error, returns C<undef> in scalar context, or an empty list in list context.

=head1 METHODS

=head2 algo

    # or 'bcrypt', 'sha256', 'sha512'
    $ht->algo( 'md5' );
    my $which = $ht->algo;

Sets or gets the hashing algorithm used by L</make> when C<create> is true: C<md5>, C<bcrypt>, C<sha256>, or C<sha512>. Default is C<md5>

=head2 bcrypt_cost

    # 04..31
    $ht->bcrypt_cost(12);
    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.