The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Crypt-PBE-0.103
River stage zero No dependents
++
/ Crypt::PBE::PBKDF2

NAME

Crypt::PBE::PBKDF2 - Perl extension for PKCS #5 Password-Based Key Derivation Function 2 (PBKDF2)

SYNOPSIS

    use Crypt::PBE::PBKDF2;

    # OO style

    my $pbkdf2 = Crypt::PBE::PBKDF2->new(
        password   => $password,
        salt       => $salt,
        prf        => 'hmac-sha256'
    );

    $pbkdf2->derived_key;           # Byte
    $pbkdf2->derived_key_base64     # Base64 encoded
    $pbkdf2->derived_key_hex        # Hex


    use Crypt::PBE::PBKDF2 qw(pbkdf2_hmac_sha1 pbkdf2_hmac_sha1_hex pbkdf2_base64 ...);

    # Functional style

    $derived_key = pbkdf2 ( %params );           # Byte
    $derived_key = pbkdf2_base64 ( %params );    # Base64 encoded
    $derived_key = pbkdf2_hex ( %params );       # Hex

    # Functional style helpers
    $derived_key = pbkdf2_hmac_sha1 ( %params );
    $derived_key = pbkdf2_hmac_sha1_hex ( %params );
    $derived_key = pbkdf2_hmac_sha1_base64 ( %params );

    $derived_key = pbkdf2_hmac_sha224_hex ( %params );
    $derived_key = pbkdf2_hmac_sha256_base64 ( %params );
    $derived_key = pbkdf2_hmac_sha384_hex ( %params );
    $derived_key = pbkdf2_hmac_sha512_base64 ( %params );

DESCRIPTION

PBKDF2 applies a pseudorandom function, such as hash-based message authentication code (HMAC), to the input password or passphrase along with a salt value and repeats the process many times to produce a derived key, which can then be used as a cryptographic key in subsequent operations.

CONSTRUCTOR

Crypt::PBE::PBKDF2->new ( %params )

Params:

  • password : The password to use for the derivation

  • salt : The salt to use for the derivation. This value should be generated randomly.

  • prf : HMAC PRF (pseudo-random function) name (default "hmac-sha1")

  • count : The number of internal iteractions to perform for the derivation key (default "1_000")

  • dk_len : The length of derived key (default "0" -- PRF default length)

METHODS

$pbkdf2->derived_key

Return the derived key in raw output (byte).

$pbkdf2->derived_key_base64

Return the derived key in Base64 encoded format.

$pbkdf2->derived_key_hex

Return the derived key in HEX format.

$pbkdf2->validate ( $derived_key, $password )

Return the validation test for provided password and derived key.

    if ($pbkdf2->validate( $my_derived_key, $params->{password} )) {
        say "Valid password";
    } else {
        say "Invalid password";
    }

$pbkdf2->prf

Return the PRF (Pseudo-Random function) name.

$pbkdf2->count

Return the iteration count number.

$pbkdf2->derived_key_length

Return the derived key length.

FUNCTIONS

pbkdf2 ( prf => ..., password => ..., salt => ..., [ count => 1_000, dk_len => 0 ] )

Return derived key using PBKDF2 function:

    my $derived_key = pbkdf2 (
        prf      => 'hmac-sha1',
        password => 'mypassword',
        salt     => my_random_byte_sub(), 
        count    => 2_000
    );

    print length($derived_key)      # 20

pbkdf2_base64 ( prf => ..., password => ..., salt => ..., [ count => 1_000, dk_len => 0 ] )

Return derived key in Base64 using PBKDF2 function.

pbkdf2_hex ( prf => ..., password => ..., salt => ..., [ count => 1_000, dk_len => 0 ] )

Return derived key in HEX using PBKDF2 function.

pbkdf2_ldap ( prf => ..., password => ..., salt => ..., [ count => 1_000 ] )

Return derived key in LDAP {PBKDF2} schema using PBKDF2 function.

EXPORTABLE HELPER FUNCTIONS

Return the derived key using SHA1/224/256/384/512 HMAC digest (Java-style):

PBKDF2WithHmacSHA1
PBKDF2WithHmacSHA224
PBKDF2WithHmacSHA256
PBKDF2WithHmacSHA384
PBKDF2WithHmacSHA512

Return the derived key using SHA1/224/256/384/512 HMAC digest:

pbkdf2_hmac_sha1
pbkdf2_hmac_sha224
pbkdf2_hmac_sha256
pbkdf2_hmac_sha384
pbkdf2_hmac_sha512

Return the derived key using SHA1/224/256/384/512 HMAC digest in Base64:

pbkdf2_hmac_sha1_base64
pbkdf2_hmac_sha224_base64
pbkdf2_hmac_sha256_base64
pbkdf2_hmac_sha384_base64
pbkdf2_hmac_sha512_base64

Return the derived key using SHA1/224/256/384/512 HMAC digest in HEX:

pbkdf2_hmac_sha1_hex
pbkdf2_hmac_sha224_hex
pbkdf2_hmac_sha256_hex
pbkdf2_hmac_sha384_hex
pbkdf2_hmac_sha512_hex

Return the derived key using SHA1/224/256/384/512 HMAC digest in {PBKDF2} LDAP schema:

pbkdf2_hmac_sha1_ldap
pbkdf2_hmac_sha256_ldap
pbkdf2_hmac_sha512_ldap

SUPPORT

Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker at https://github.com/giterlizzi/perl-Crypt-PBE/issues. You will be notified automatically of any progress on your issue.

Source Code

This is open source software. The code repository is available for public review and contribution under the terms of the license.

https://github.com/giterlizzi/perl-Crypt-PBE

    git clone https://github.com/giterlizzi/perl-Crypt-PBE.git

AUTHOR

  • Giuseppe Di Terlizzi <gdt@cpan.org>

SEE ALSO

Crypt::PBE::PBKDF1
[RFC2898] PKCS #5: Password-Based Cryptography Specification Version 2.0 (https://tools.ietf.org/html/rfc2898)
[RFC8018] PKCS #5: Password-Based Cryptography Specification Version 2.1 (https://tools.ietf.org/html/rfc8018)
[RFC6070] PKCS #5: Password-Based Key Derivation Function 2 (PBKDF2) - Test Vectors (https://tools.ietf.org/html/rfc6070)
[RFC2307] An Approach for Using LDAP as a Network Information Service (https://tools.ietf.org/html/rfc2307)

LICENSE AND COPYRIGHT

This software is copyright (c) 2020-2023 by Giuseppe Di Terlizzi.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.