/ 
Crypt-HSM-0.018
River stage one • 2 direct dependents • 2 total dependents
/ Crypt::HSM::Session

NAME

Crypt::HSM::Session - A PKCS11 session

VERSION

version 0.018

SYNOPSIS

 $session->login('user', $password) if defined $password;

 my ($key) = $session->find_objects({ label => $label, encrypt => 1 });
 if (not $key) {
	$key = $session->generate_key('aes-key-gen', { label => $label, sensitive => 1, "value-len" => 32 });
 }
 my $iv = $session->generate_random(16);
 $session->encrypt('aes-cbc', $key, $plaintext, $iv);

DESCRIPTION

This represents a session with a PKCS module such as an HSM. It does most of the cryptographic work of using a PKCS11 interface.

Constants

This module uses hundreds of constants from the PKCS11 standard as short stings. They're all lowercased, without prefix and with hyphens instead of underscores. So CKM_SHA256_RSA_PKCS becomes 'sha256-rsa-pkcs'. In KDF names, the <-kdf> part is eliminated.

Types

Various types of arguments are recurring its methods, these are:

key/object

This is an identifier that refers to resource inside the HSM, it has no meaning outside of it.

mechanism

This is a mechanism for a cryptographic operation, e.g. 'aes-gcm', 'sha256-rsa-pkcs' or 'sha512-hmac'. The list of supported mechanisms can be retrieved using the mechanisms method on the Crypt::HSM object.

attributes

This is an hash of attributes. The key is the name of the attribute (e.g. 'class', 'sensitive'), the value depends on the key but is usually either an integer, a string or a bool.

Additional arguments

Many functions will also take one or more mechanism specific additional arguments after their generic arguments, for example an IV or nonce for a symmetric cipher, or a public key for a Diffie-Hellman derivation. Where supported these are documented in Crypt::HSM::Mechanism.

METHODS

create_object($attributes)

Create an object with the given $attribute hash. This returns a Crypt::HSM::Object object.

decrypt($mechanism, $key, $ciphertext, ...)

Decrypt $ciphertext with $mechanism and $key. This may take mechanism dependent additional arguments such as an IV.

derive_key($mechanism, $key, $attributes, ...)

Derive a new key from $key, using mechanism and setting $attributes on it. This may take mechanism dependent additional arguments. This returns a Crypt::HSM::Object object.

digest($mechanism, $key, $input, ...)

Digest $input with $mechanism and $key. This may take mechanism dependent additional arguments.

encrypt($mechanism, $key, $plaintext, ...)

Encrypt $plaintext with $mechanism and $key. This may take mechanism dependent additional arguments such as an IV.

find_objects($attributes)

Find all objects that satisfy the given $attributes. This returns a list of Crypt::HSM::Object objects.

generate_key($mechanism, \%attributes)

Generate a new key for $mechanism with $attributes. Some relevant attributes are:

  • label

    A label to your key, this helps with alter retreiving the key.

  • token

    If true this will store the key on the token, if false it will create a session key.

  • sensitive

    Sensitive keys cannot be revealed in plaintext, this is almost always desired for non-public keys.

  • extractable

    This allows the key to be extractable, for example using wrapping.

  • wrap-with-trusted

    If true a key can only be extracted with a trusted key

  • trusted

    This marks the key as trusted, this usually requires logging in as security officer.

  • private

    If true the key can't be used without logging in.

  • value-len

    This sets the length of a key, this can be useful when creating a 'generic-secret-key-gen' in particular.

Most of these have implementation-specific defaults. This returns a Crypt::HSM::Object object.

generate_keypair($mechanism, \%public_attributes, \%private_attributes)

This generates a key pair. The attributes for the public and private keys work similar to `generate_key`. This returns two Crypt::HSM::Object objects.

generate_random($length)

This generate $length bytes of randomness.

info()

This returns information about the current session.

init_pin($pin)

This initializes the PIN for this slot.

login($type, $pin)

Log in the current session. $type should be either 'user' (most likely), 'so' (security officer, for elevated privileges), or 'context-dependent'. $pin is your password. This is needed on some providers but not all.

logout()

Log the current session out.

open_decrypt($mechanism, $key, ...)

Start a decryption with $mechanism and $key. This returns a Crypt::HSM::Decrypt object. This may take mechanism dependent additional arguments such as an IV.

open_digest($mechanism, ...)

Start a digest with $mechanism. This returns a Crypt::HSM::Digest object. This may take mechanism dependent additional arguments.

open_encrypt($mechanism, $key, ...)

Start an encryption with $mechanism and $key. This returns a Crypt::HSM::Encrypt object. This may take mechanism dependent additional arguments such as an IV.

open_sign($mechanism, $key, ...)

Start an signing with $mechanism and $key. This returns a Crypt::HSM::Sign object. This may take mechanism dependent additional arguments.

open_verify($mechanism, $key, ...)

Start an verification with $mechanism and $key. This returns a Crypt::HSM::Verify object. This may take mechanism dependent additional arguments.

provider()

Returns the provider object for this session.

seed_random($seed)

Mix additional seed material into the token’s random number generator.

set_pin($old_pin, $new_pin)

This changes the PIN from $old_pin to $new_pin.

sign($mechanism, $key, $input, ...)

This creates a signature over $input using $mechanism and $key. This may take mechanism dependent additional arguments.

slot()

Returns the slot identifier used for this session.

unwrap_key($mechanism, $unwrap_key, $wrapped_key, $attributes, ...)

This unwraps the key wrapped in the bytearray $wrapped_key using mechanism and key $unwrap_key, setting $attributes on the new key. This returns a Crypt::HSM::Object object.

verify($mechanism, $key, $data, $signature, ...)

Verify that $signature matches $data, using $mechanism and $key. This may take mechanism dependent additional arguments

wrap_key($mechanism, $wrap_key, $key, ...)

This wraps key $key using $mechanism and key $wrap_key.

AUTHOR

Leon Timmermans <fawaka@gmail.com>

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.