/ 
Crypt-HSM-0.025
River stage one • 2 direct dependents • 2 total dependents
⭐ Starred 0 GitHub stars
/ Crypt::HSM::Slot

NAME

Crypt::HSM::Slot - A PKCS11 slot

VERSION

version 0.025

SYNOPSIS

my $session = $slot->open_session;

DESCRIPTION

This represents a slot on a PKCS implementation.

METHODS

open_session(%flags)

This opens a Crypt::HSM::Session to this slot. It takes named arguments arguments, currently only one is defined:

  • rw-session

    If set to a true value, a read-write session is opened.

mechanisms()

This returns all mechanisms supported by the token in the slot as Crypt::HSM::Mechanism objects.

mechanism($name)

This returns the named mechanism as a Crypt::HSM::Mechanism object.

id()

This returns the identifier of this slot.

close_all_sessions()

This closes all sessions on this slot.

info()

This returns a hash with information about the slot. This contains the following entries:

  • description

    Description of the slot.

  • manufacturer-id

    ID of the slot manufacturer.

  • flags

    Flags on the slot, this hash contains of the following entries""

    • token-present

      True if a token is present in the slot (e.g., a device is in the reader).

    • removable-device

      True if the reader supports removable devices.

      For a given slot, the value of this flag never changes. In addition, if this flag is not set for a given slot, then the token-present flag for that slot is always set. That is, if a slot does not support a removable device, then that slot always has a token in it.

    • hw-slot

      True if the slot is a hardware slot, as opposed to a software slot implementing a “soft token”.

  • hardware-version

    Version number of the slot’s hardware

  • firmware-version

    Version number of the slot’s firmware

token_info()

This returns a hash with information about the token in the slot. This contains the following entries:

  • label

    Application-defined label, assigned during token initialization.

  • manufacturer-id

    ID of the device manufacturer.

  • model

    Model of the device.

  • serial-number

    Serial number of the device.

  • flags

    Flags on the slot, this hash contains the following entries:

    • rng

      True if the token has its own random number generator

    • write-protected

      True if the token is write-protected (see below)

    • login-required

      True if there are some cryptographic functions that a user MUST be logged in to perform

    • user-pin-initialized

      True if the normal user’s PIN has been initialized

    • restore-key-not-needed

      True if a successful save of a session’s cryptographic operations state always contains all keys needed to restore the state of the session

    • clock-on-token

      True if token has its own hardware clock

    • protected-authentication-path

      True if token has a “protected authentication path”, whereby a user can log into the token without passing a PIN through the Cryptoki library

    • dual-crypto-operations

      True if a single session with the token can perform dual cryptographic operations

    • token-initialized

      True if the token has been initialized using init_token or an equivalent mechanism outside the scope of this standard. Calling init_token when this flag is set will cause the token to be reinitialized.

    • secondary-authentication

      True if the token supports secondary authentication for private key objects (deprecated).

    • user-pin-count-low

      True if an incorrect user login PIN has been entered at least once since the last successful authentication.

    • user-pin-final-try

      True if supplying an incorrect user PIN will cause it to become locked.

    • user-pin-locked

      True if the user PIN has been locked. User login to the token is not possible.

    • user-pin-to-be-changed

      True if the user PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card.

    • so-pin-count-low

      True if an incorrect SO login PIN has been entered at least once since the last successful authentication.

    • so-pin-final-try

      True if supplying an incorrect SO PIN will cause it to become locked.

    • so-pin-locked

      True if the SO PIN has been locked. SO login to the token is not possible.

    • so-pin-to-be-changed

      True if the SO PIN value is the default value set by token initialization or manufacturing, or the PIN has been expired by the card.

    • error-state

      True if the token failed a FIPS 140-2 self-test and entered an error state.

  • max-session-count

    Maximum number of sessions that can be opened with the token at one time by a single application

  • session-count

    Number of sessions that this application currently has open with the token

  • max-rw-session-count

    Maximum number of read/write sessions that can be opened with the token at one time by a single application

  • rw-session-count

    Number of read/write sessions that this application currently has open with the token

  • max-pin-len

    Maximum length in bytes of the PIN

  • min-pin-len

    Minimum length in bytes of the PIN

  • total-public-memory

    The total amount of memory on the token in bytes in which public objects may be stored

  • free-public-memory

    The amount of free (unused) memory on the token in bytes for public objects

  • total-private-memory

    The total amount of memory on the token in bytes in which private objects may be stored

  • free-private-memory

    The amount of free (unused) memory on the token in bytes for private objects

  • hardware-version

    Version number of the slot’s hardware

  • firmware-version

    Version number of the slot’s firmware

  • utc-time

    Current time as a character-string of length 16, represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved ‘0’ characters). The value of this field only makes sense for tokens equipped with a clock, as indicated in the token information flags.

init_token($pin, $label)

This initializes a token on the slot, with the associalted $pin and $label (max 32 characters).

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.