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 but only create the former.

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.

• slot

  The slot used on the provider, this defaults to the first listed slot.

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