view release on metacpan or  search on metacpan

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

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.

=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