NAME

Developer::Dashboard::Crypto::PBKDF2 - native PBKDF2 adapter

PURPOSE

This module binds OpenSSL's one-shot PBKDF2-HMAC-SHA256 implementation through FFI::Platypus. It is a narrow adapter for the dashboard helper-authentication hot path; it does not translate or accelerate arbitrary Perl subroutines.

WHY IT EXISTS

The prior derivation called the XS HMAC function once per PBKDF2 round from a Perl loop. A single native PBKDF2 call avoids that repeated Perl/native boundary while retaining the existing digest, output size, and iteration count. The portable Perl implementation remains the documented path when no compatible system libcrypto or optional FFI module is available, or when input byte semantics cannot safely cross the FFI boundary. Only absence of the requested optional FFI module selects the fallback; other module-load errors remain visible.

WHEN TO USE

Use this module only for SHA-256 PBKDF2 derivation with scalar password/salt values representable as Perl byte strings and a positive integer work factor. Do not use it to reduce the iteration count or to parallelize one PBKDF2 chain; the chain is intentionally sequential.

HOW TO USE

Call native_available to inspect whether the optional FFI modules and a compatible OpenSSL library are available. Call derive_sha256 with named password, salt, and iterations arguments. An undefined result means the caller should execute its explicit Perl implementation. Library-binding and native-call failures die with a visible error rather than being hidden as fallback.

WHAT USES IT

Developer::Dashboard::Auth calls this adapter when creating and verifying PBKDF2 helper-user records. The Auth module retains the existing Digest::SHA implementation for unsupported input and systems without libcrypto.

EXAMPLES

Example 1:

my $digest = Developer::Dashboard::Crypto::PBKDF2->derive_sha256(
  password => $password,
  salt => $salt,
  iterations => 210_000,
);

Derive the same stored PBKDF2-SHA256 key through OpenSSL when the adapter can preserve the input byte semantics.

Example 2:

if (Developer::Dashboard::Crypto::PBKDF2->native_available) {
    print "OpenSSL PBKDF2 acceleration is available\n";
}

Check whether the current machine has a compatible native crypto library.

Example 3:

prove -lv t/651-crypto-pbkdf2-ffi.t

Run digest-parity, unsupported-Unicode, missing-library, and missing-optional-module tests.