NAME

Crypt::PKCS11 - Full-fledged PKCS #11 v2.30 interface

SYNPOSIS

  use Crypt::PKCS11;

  # Create the main PKCS #11 object, load a PKCS #11 provider .so library and initialize the module
  my $pkcs11 = Crypt::PKCS11->new;
  $pkcs11->load(...);
  $pkcs11->Initialize;

  # Create a new session and log in
  my $session = $pkcs11->OpenSession(...);
  $session->Login(...);

  # Create the public key template
  my $publicKeyTemplate = Crypt::PKCS11::Attributes->new->push(
      Crypt::PKCS11::Attribute::Encrypt->new->set(1),
      Crypt::PKCS11::Attribute::Verify->new->set(1),
      Crypt::PKCS11::Attribute::Wrap->new->set(1),
      Crypt::PKCS11::Attribute::PublicExponent->new->set(0x01, 0x00, 0x01),
      Crypt::PKCS11::Attribute::Token->new->set(1),
      Crypt::PKCS11::Attribute::ModulusBits->new->set(768)
  );

  # Create the private key template
  my $privateKeyTemplate = Crypt::PKCS11::Attributes->new->push(
      Crypt::PKCS11::Attribute::Private->new->set(1),
      Crypt::PKCS11::Attribute::Id->new->set(123),
      Crypt::PKCS11::Attribute::Sensitive->new->set(1),
      Crypt::PKCS11::Attribute::Decrypt->new->set(1),
      Crypt::PKCS11::Attribute::Sign->new->set(1),
      Crypt::PKCS11::Attribute::Unwrap->new->set(1),
      Crypt::PKCS11::Attribute::Token->new->set(1)
  );

  # Create a public and private key pair
  my ($publicKey, $privateKey) = $session->GenerateKeyPair(
      Crypt::PKCS11::CK_MECHANISM->new->set_mechanism(...),
      $publicKeyTemplate,
      $privateKeyTemplate);

  # Encrypt data
  my $data = ...;
  $session->EncryptInit(
      Crypt::PKCS11::CK_MECHANISM->new->set_mechanism(...),
      $privateKey);
  my $encryptedData = $session->Encrypt($data);
  $encryptedData .= $session->EncryptFinal;

  # Decrypt data
  $session->DecryptInit(
      Crypt::PKCS11::CK_MECHANISM->new->set_mechanism(...),
      $privateKey);
  $data = $session->Decrypt($encryptedData);
  $data .= $session->DecryptFinal;

  # Finalize the PKCS #11 module and unload the provider .so library
  $pkcs11->Finalize;
  $pkcs11->unload;

DESCRIPTION

Crypt::PKCS11 provides a full-fedged PKCS #11 v2.30 interface for Perl and together with a PKCS #11 proivder .so library you can use all the functionallity a Hardware Security Module (HSM) has to offer from within Perl.

Other modules/pod sections included are:

Crypt::PKCS11::XS: XS layer containing wrappers for all PKCS #11 functions that converts Perl data structures to/from PKCS #11 specific data structures.
Crypt::PKCS11::Session: A module handling everything related to a PKCS #11 session.
Crypt::PKCS11::Object: A module that represent a PKCS #11 object which for example can be a public or private key.
Crypt::PKCS11::Attribute: A module that represent a PKCS #11 attribute that are used in templates when for example creating keys. This is only a base class, see Crypt::PKCS11::Attributes for a list of all available attributes.
Crypt::PKCS11::Attributes: A module to handle a set of Crypt::PKCS11::Attribute objects and also lists all available PKCS #11 attributes.
Crypt::PKCS11::constant: List of all PKCS #11 constants.
Crypt::PKCS11::Attribute::AttributeArray: A base module that handles nested PKCS #11 attributes.
Crypt::PKCS11::Attribute::ByteArray: A base module that handles byte array attributes.
Crypt::PKCS11::Attribute::CK_BBOOL: A base module that handles boolean attributes.
Crypt::PKCS11::Attribute::CK_BYTE: A base module that handles one byte attributes.
Crypt::PKCS11::Attribute::CK_DATE: A base module that handles date attributes.
Crypt::PKCS11::Attribute::CK_ULONG: A base module that handles an unsigned long attributes.
Crypt::PKCS11::Attribute::RFC2279string: A base module that handles RFC 2279 string attributes.
Crypt::PKCS11::Attribute::UlongArray: A base module that handles unsigned long array attributes.
Crypt::PKCS11::Attribute::Value: A base module that handles attributes containing either a byte array or a binary string.

QUALITY ASSURANCE AND TESTING

This module is currently tested on Ubuntu 12.04 and with SoftHSM version 1.3.7 and 2.0.0b2 as PKCS #11 providers / HSM backends. It uses Test::LeakTrace to detect leaks and Devel::Cover to provide coverage reports. The goal is to always be non-leaking and to have 100% coverage. See README.testing.md for more information how to test.

  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  File                           stmt   bran   cond    sub    pod   time  total
  ---------------------------- ------ ------ ------ ------ ------ ------ ------
  blib/lib/Crypt/PKCS11.pm      100.0  100.0  100.0  100.0  100.0   92.6  100.0
  ...Crypt/PKCS11/Attribute.pm  100.0  100.0  100.0  100.0  100.0    0.1  100.0
  ...tribute/AttributeArray.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...11/Attribute/ByteArray.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...S11/Attribute/CK_BBOOL.pm  100.0  100.0    n/a  100.0  100.0    0.0  100.0
  ...CS11/Attribute/CK_BYTE.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...CS11/Attribute/CK_DATE.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...S11/Attribute/CK_ULONG.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...ttribute/RFC2279string.pm  100.0  100.0    n/a  100.0  100.0    0.0  100.0
  ...1/Attribute/UlongArray.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...PKCS11/Attribute/Value.pm  100.0  100.0  100.0  100.0  100.0    0.0  100.0
  ...rypt/PKCS11/Attributes.pm  100.0  100.0  100.0  100.0  100.0    4.8  100.0
  ...ib/Crypt/PKCS11/Object.pm  100.0  100.0  100.0  100.0  100.0    1.9  100.0
  ...b/Crypt/PKCS11/Session.pm  100.0  100.0  100.0  100.0  100.0    0.5  100.0
  crypt_pkcs11.c                100.0  100.0    n/a    n/a    n/a    n/a  100.0
  crypt_pkcs11_struct.c         100.0  100.0    n/a    n/a    n/a    n/a  100.0
  pkcs11.xs                     100.0    n/a    n/a    n/a    n/a    n/a  100.0
  pkcs11_struct.xs              100.0    n/a    n/a    n/a    n/a    n/a  100.0
  Total                         100.0  100.0  100.0  100.0  100.0  100.0  100.0
 ---------------------------- ------ ------ ------ ------ ------ ------ ------

This module has been tested with the following PKCS #11 providers and operating systems:

Ubuntu Server 12.04 using SoftHSM version 1.3.7 and 2.0.0b2

More platforms and PKCS #11 providers will be added in the future.

RETURN VALUES AND ERROR HANDLING

This is the general return value and error handling for all methods unless otherwise stated.

On XS layer errors, when called from within these methods, all methods returns false (0/undef) and the XS layer error can be retrieved with $pkcs11->errno for the number and $pkcs11->errstr for the message.

For errors from the methods themself, the method will confess (croak) with the error message.

CONSTANTS

All PKCS #11 constants (C #define's) can be imported by specifying the tag :constant when using the module, see PKCS #11 documentation for a list of all constants.

  use Crypt::PKCS11 qw(:constant);

There are also hashes for reverse lookup available, to get the name of the constant in text, per constant section using the tag :constant_names, for example if you wish to reverse lookup a mechanism you can use the %CKM_NAME hash.

  use Crypt::PKCS11 qw(:constant_names);
  ...
  print "Support for $CKM_NAME{$mechanism} found.\n";

Beside all constants that exists in PCKS #11 these have been added:

CK_ULONG_SIZE: Contains the size of CK_ULONG type that will be different depending on the operating system.

METHODS

For more extensive documentation about the methods, data structures and types please see http://www.cryptsoft.com/pkcs11doc/v230/ .

$pkcs11 = Crypt::PKCS11->new

Returns a new Crypt::PKCS11 object.

$pkcs11->load ($so)

Loads the PKCS #11 provider .so library specified by $so.

$pkcs11->unload

Unloads the PKCS #11 provider .so library, done automatically on destruction of the object.

$pkcs11->Initialize ([initArgs => ... ])

Initialize the PKCS #11 library, this must be done before using the PKCS #11 library. The initialization arguments can be given as one hash reference or as a hash.

NOTE: For all Mutex CODE references the global callback will be set, there is no support for individual callbacks per Crypt::PKCS11 object.

All of the Mutex arguments needs to be set if any should be used.

For more information about mutex callbacks and how to use them please see Crypt::PKCS11::MutexCallbacks.

The following initialization arguments can be used:

CreateMutex: A CODE reference to a function to use for creating mutex objects. The global callback for CreateMutex will also be set.
DestroyMutex: A CODE reference to a function to use for destroying mutex objects. The global callback for DestroyMutex will also be set.
LockMutex: A CODE reference to a function to use for locking mutex objects. The global callback for LockMutex will also be set.
UnlockMutex: A CODE reference to a function to use for unlocking mutex objects. The global callback for UnlockMutex will also be set.
flags: Bit flags specifying options for initialization.

$pkcs11->Finalize

Finalize the PKCS #11 library, done automatically on destruction of the object.

< %hash || $hash_ref > = $pkcs11->GetInfo

Return information about the PKCS #11 library as a hash, if called in list context, or as a hash reference, if called in scalar context.

Fields in hash are as follows:

cryptokiVersion

Cryptoki interface version number, for compatibility with future revisions of this interface, as a hash reference.

major: Major version part.
minor: Minor version part.

manufacturerID

ID of the Cryptoki library manufacturer, padded with the blank character (' ').

flags

Bit flags reserved for future versions.

libraryDescription

Character-string description of the library, padded with the blank character (' ').

libraryVersion

Cryptoki library version number as a hash reference.

major: Major version part.
minor: Minor version part.

< @array || $array_ref > = $pkcs11->GetSlotList ([$tokenPresent = undef])

Return a list of slot IDs as an array, if called in list context, or as an array reference, if called in scalar context.

$tokenPresent: Optional argument which is default to false. If set to true then only the slot IDs which has tokens will be returned.

< %hash || $hash_ref > = $pkcs11->GetSlotInfo ($slotID)

Return information about a slot as a hash, if called in list context, or as a hash reference, if called in scalar context.

$slotID: The slot ID to return information about.

Fields in hash are as follows:

slotDescription

Character-string description of the slot, padded with the blank character (' ').

manufacturerID

ID of the slot manufacturer, padded with the blank character (' ').

flags

Bits flags that provide capabilities of the slot, see PKCS #11 documentation for the list of flags available.

hardwareVersion

Version number of the slot's hardware as a hash reference.

major: Major version part.
minor: Minor version part.

firmwareVersion

Version number of the slot's firmware as a hash reference.

major: Major version part.
minor: Minor version part.

< %hash || $hash_ref > = $pkcs11->GetTokenInfo ($slotID)

Return information about tokens in a slot as a hash, if called in list context, or as a hash reference, if called in scalar context.

$slotID: The slot ID to return information about.

Fields in hash are as follows:

label

Application-defined label, assigned during token initialization, padded with the blank character (' ').

manufacturerID

ID of the device manufacturer, padded with the blank character (' ').

model

Model of the device, padded with the blank character (' ').

serialNumber

Character-string serial number of the device, padded with the blank character (' ').

flags

Bit flags indicating capabilities and status of the device, see PKCS #11 documentation for the list of flags available.

ulMaxSessionCount

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

ulSessionCount

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

ulMaxRwSessionCount

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

ulRwSessionCount

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

ulMaxPinLen

Maximum length in bytes of the PIN.

ulMinPinLen

Minimum length in bytes of the PIN.

ulTotalPublicMemory

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

ulFreePublicMemory

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

ulTotalPrivateMemory

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

ulFreePrivateMemory

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

hardwareVersion

Version number of hardware as a hash reference.

major: Major version part.
minor: Minor version part.

firmwareVersion

Version number of firmware as a hash reference.

major: Major version part.
minor: Minor version part.

utcTime

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.

< @array || $array_ref > = $pkcs11->GetMechanismList ($slotID)

Return a list of mechanism for a slot as an array, if called in list context, or as an array reference, if called in scalar context.

$slotID: The slot ID to return information about.

< %hash || $hash_ref > = $pkcs11->GetMechanismInfo ($slotID, $mechanismType)

Return information about mechanism for a slot as a hash, if called in list context, or as a hash reference, if called in scalar context.

$slotID: The slot ID to return information about.
$mechanismType: The mechanism type to return information about.

Fields in hash are as follows:

ulMinKeySize: The minimum size of the key for the mechanism (whether this is measured in bits or in bytes is mechanism-dependent).
ulMaxKeySize: The maximum size of the key for the mechanism (whether this is measured in bits or in bytes is mechanism-dependent).
flags: Bit flags specifying mechanism capabilities.

$pkcs11->InitToken ($slotID, [$pin = undef], $label)

Initialize a token.

$slotID: The slot ID to initialize.
$pin: Optional argument that specifies the PIN to use when initializing.
$label: The label of the token.

$session = $pkcs11->OpenSession ($slotID, [$flags = 0, $notifycb = undef])

Open a new PKCS #11 session and return a Crypt::PKCS11::Session object.

$slotID: The slot ID to open a session for.
$flags: Optional argument that indicates the type of session to open.
$notifycb: Optional argument for a callback CODE reference to be used when notifying the application of certain events.

$pkcs11->CloseAllSessions ($slotID)

Close all current session with the slot specified.

$slotID: The slot ID to close sessions for.

$pkcs11->WaitForSlotEvent ([$flags = 0])

Waits for a slot event, such as token insertion or token removal, to occur. Will block unless the flag CKF_DONT_BLOCK is used.

$flags: Optional argument to determines whether or not the method blocks.

$errno = $pkcs11->errno

Return the last error number, can be used after a method returns false.

$errstr = $pkcs11->errstr

Return the last error message, can be used after a method returns false.

NOTE

Derived from the RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki)

AUTHOR

Jerry Lundström <lundstrom.jerry@gmail.com>

REPORTING BUGS

Report bugs at https://github.com/dotse/p5-Crypt-PKCS11/issues .

LICENSE

  Copyright (c) 2015 Jerry Lundström <lundstrom.jerry@gmail.com>
  Copyright (c) 2015 .SE (The Internet Infrastructure Foundation)
  All rights reserved.

  Redistribution and use in source and binary forms, with or without
  modification, are permitted provided that the following conditions
  are met:
  1. Redistributions of source code must retain the above copyright
     notice, this list of conditions and the following disclaimer.
  2. Redistributions in binary form must reproduce the above copyright
     notice, this list of conditions and the following disclaimer in the
     documentation and/or other materials provided with the distribution.

  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

To install Crypt::PKCS11, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Crypt::PKCS11

CPAN shell

perl -MCPAN -e shell
install Crypt::PKCS11

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNPOSIS

DESCRIPTION

QUALITY ASSURANCE AND TESTING

RETURN VALUES AND ERROR HANDLING

CONSTANTS

METHODS

NOTE

AUTHOR

REPORTING BUGS

LICENSE

Module Install Instructions