The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Crypt-HSM-0.004
River stage one • 2 direct dependents • 2 total dependents
++
/ Crypt::HSM::Session

NAME

Crypt::HSM::Session - A PKCS11 session

VERSION

version 0.004

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 $attr = $session->get_attribute

DESCRIPTION

This represents a session with a PKCS module such as an HSM. It does all

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

generate_random($length)

This generate $length bytes of randomness.

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

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.

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

This unwraps the key wrapped in the bytearray $wrapped_key using mechanism and $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 using $mechanism and $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.