NAME

Crypt::HSM::Session - A PKCS11 session

VERSION

version 0.016

SYNOPSIS

 $session->encrypt('aes-cbc', $key, $plaintext, $iv);

 $session->sign('sha256-hmac', $key, $data);

 $session->verify('sha256-rsa-pkcs', $key, $data, $signature);

 my $key = $session->generate_key($type, { token => 1, sensitive => 1 });

 my @keys = $session->find_objects({ class => 'secret-key' });

 my $attrs = $session->get_attributes($key, [ 'private', 'sensitive' ]);

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.

Cryptographic methods taking taking an argument will also take zero or more mechanism specific arguments after their generic arguments, for example an IV or nonce for a symmetric cipher that uses such, or a public key for a Diffie-Hellman derivation.

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.

METHODS

copy_object($object, $attributes)

Copy an object, optionally adding/modifying the given attributes.

create_object($attributes)

Create an object with the given $attribute hash.

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

Decrypt $ciphertext with $mechanism and $key.

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

Derive a new key from $key, using mechanism and setting $attributes on it.

destroy_object($object)

This deletes the object with the identifier $object.

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

Digest $input with $mechanism and $key.

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

Encrypt $plaintext with $mechanism and $key.

find_objects($attributes)

Find all objects that satisfy the given $attributes.

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.

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

generate_random($length)

This generate $length bytes of randomness.

get_attribute($object, $attribute_name)

This returns the value of the named attribute.

get_attributes($object, $attribute_list)

This returns a hash with the attributes that are asked for.

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.

logout()

Log the current session out.

object_size($object)

This returns the size of $object.

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

Start a decryption with $mechanism and $key. This returns a Crypt::HSM::Decrypt object.

open_digest($mechanism, ...)

Start a digest with $mechanism. This returns a Crypt::HSM::Digest object.

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

Start an encryption with $mechanism and $key. This returns a Crypt::HSM::Encrypt object.

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

Start an signing with $mechanism and $key. This returns a Crypt::HSM::Sign object.

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

Start an verification with $mechanism and $key. This returns a Crypt::HSM::Verify object.

provider()

Returns the provider object for this session.

seed_random($seed)

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

set_attributes($object, $attributes)

This sets the $attributes on $object.

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.

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.

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

Verify that $signature matches $data, using $mechanism and $key.

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

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

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.

cpanm Crypt::HSM

perl -MCPAN -e shell
install Crypt::HSM