view release on metacpan or  search on metacpan

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

=encoding utf8

=head1 NAME

Apache2::API::Password - Create and verify HTTP Basic Auth password hashes (APR1/bcrypt/SHA-crypt)

=head1 SYNOPSIS

	use Apache2::API::Password;
    # Create a new hash from a cleartext password (random salt)
    # MD5-crypt (APR1, "$apr1$") - default
    my $ht = Apache2::API::Password->new( 'secret', create => 1 );
    my $hash = $ht->hash; # "$apr1$abcd1234$...."

    # Create APR1 with a provided salt (max 8 chars; [./0-9A-Za-z])
    my $ht2 = Apache2::API::Password->new( 'secret', create => 1, salt => 'hfT7jp2q' );
    say $ht2->hash;

    # Wrap an existing APR1 ($apr1$) hash and verify user input
    my $ht3 = Apache2::API::Password->new( '$apr1$hfT7jp2q$DcU1Hf5w2Q/9G8yqv1hbl.' );
    my $ok  = $ht3->matches( 'secret' );

    # Bcrypt ($2y$), choose a cost (04..31); defaults to 12
    my $b  = Apache2::API::Password->new('s3cret', create => 1, algo => 'bcrypt', bcrypt_cost => 12);
    say $b->hash; # "$2y$12$..."

    # SHA-crypt ($5$ = SHA-256, $6$ = SHA-512), optionally set rounds
    my $s6 = Apache2::API::Password->new('s3cret', create => 1, algo => 'sha512', sha_rounds => 150000);
    say $s6->hash; # "$6$rounds=150000$..."

    # Accessors
	my $hash_password = $ht->hash;
	# parsed from the hash
    my $salt = $ht3->salt;

=head1 VERSION

    v0.1.1

=head1 DESCRIPTION

C<Apache2::API::Password> creates and verifies password hashes used by Apache HTTP Basic Authentication. It supports:

=over 4

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