NAME

    Crypt::Passphrase::Pepper::HSM - A pepper-wrapper using hardware for
    Crypt::Passphrase

SYNOPSIS

     my $passphrase = Crypt::Passphrase->new(
         encoder => {
             module   => 'Pepper::HSM',
             provider => '/usr/lib/pkcs11/some-pkcs11.so',
             active   => '3',
             inner    => {
                 module      => 'Argon2',
                 output_size => 32,
             },
         },
     );

DESCRIPTION

    This module wraps another encoder to pepper the input to the hash. By
    using identifiers for the peppers, it allows for easy rotation of
    peppers. Unlike Crypt::Passphrase::Pepper::Simple it stores the peppers
    in a hardware security module (or some other PKCS11 implementation of
    choice) to ensure their confidentiality.

    It will be able to validate both peppered and unpeppered hashes.

METHODS

 new(%args)

    This creates a new pepper encoder. It takes the following named
    arguments:

      * inner

      This contains an encoder specification identical to the encoder field
      of Crypt::Passphrase. It is mandatory.

      * provider

      The path to the PKCS11 provider. This is mandatory.

      * active

      This is the identifier of the active pepper. This is mandatory.

      * prefix

      The prefix that is used when looking up keys in the HSM. It defaults
      to 'pepper-'.

      * pin

      The PIN that is used for logging in, if any.

      * user_type

      The type of user you're logging in with. This defaults to 'user', and
      you're unlikely to want to change that.

      * algorithm

      This is the algorithm that's used for peppering. Supported values are
      'sha1-hmac', 'sha224-hmac', 'sha256-hmac', 'sha384-hmac', and
      'sha512-hmac' (the default).

 prehash_password($password, $algorithm, $identifier)

    This prehashes the $password using the given $algorithm and
    $identifier.

AUTHOR

    Leon Timmermans <leont@cpan.org>

COPYRIGHT AND LICENSE

    This software is copyright (c) 2023 by Leon Timmermans.

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