<commit_before>=encoding utf8

=head1 NAME

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

=head1 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;

=head1 DESCRIPTION

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

Other modules/pod sections included are:

=over 4

=item Crypt::PKCS11::XS

XS layer containing wrappers for all PKCS #11 functions that converts Perl data
structures to/from PKCS #11 specific data structures.

=item Crypt::PKCS11::Session

A module handling everything related to a PKCS #11 session.

=item Crypt::PKCS11::Object

A module that represent a PKCS #11 object which for example can be a public or
private key.

=item 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
L<Crypt::PKCS11::Attributes> for a list of all available attributes.

=item Crypt::PKCS11::Attributes

A module to handle a set of Crypt::PKCS11::Attribute objects and also lists all
available PKCS #11 attributes.

=item Crypt::PKCS11::constant

List of all PKCS #11 constants.

=item Crypt::PKCS11::Attribute::AttributeArray

A base module that handles nested PKCS #11 attributes.

=item Crypt::PKCS11::Attribute::ByteArray

A base module that handles byte array attributes.

=item Crypt::PKCS11::Attribute::CK_BBOOL

A base module that handles boolean attributes.

=item Crypt::PKCS11::Attribute::CK_BYTE

A base module that handles one byte attributes.

=item Crypt::PKCS11::Attribute::CK_DATE

A base module that handles date attributes.

=item Crypt::PKCS11::Attribute::CK_ULONG

A base module that handles an unsigned long attributes.

=item Crypt::PKCS11::Attribute::RFC2279string

A base module that handles RFC 2279 string attributes.

=item Crypt::PKCS11::Attribute::UlongArray

A base module that handles unsigned long array attributes.

=item Crypt::PKCS11::Attribute::Value

A base module that handles attributes containing either a byte array or a binary
string.

=back

=head1 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<commit_msg>Add list of CK_* pods in Crypt::PKCS11 pod.<commit_after>=encoding utf8

=head1 NAME

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

=head1 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;

=head1 DESCRIPTION

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

Other modules/pod sections included are:

=over 4

=item Crypt::PKCS11::XS

XS layer containing wrappers for all PKCS #11 functions that converts Perl data
structures to/from PKCS #11 specific data structures.

=item Crypt::PKCS11::Session

A module handling everything related to a PKCS #11 session.

=item Crypt::PKCS11::Object

A module that represent a PKCS #11 object which for example can be a public or
private key.

=item 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
L<Crypt::PKCS11::Attributes> for a list of all available attributes.

=item Crypt::PKCS11::Attributes

A module to handle a set of Crypt::PKCS11::Attribute objects and also lists all
available PKCS #11 attributes.

=item Crypt::PKCS11::constant

List of all PKCS #11 constants.

=item Crypt::PKCS11::Attribute::AttributeArray

A base module that handles nested PKCS #11 attributes.

=item Crypt::PKCS11::Attribute::ByteArray

A base module that handles byte array attributes.

=item Crypt::PKCS11::Attribute::CK_BBOOL

A base module that handles boolean attributes.

=item Crypt::PKCS11::Attribute::CK_BYTE

A base module that handles one byte attributes.

=item Crypt::PKCS11::Attribute::CK_DATE

A base module that handles date attributes.

=item Crypt::PKCS11::Attribute::CK_ULONG

A base module that handles an unsigned long attributes.

=item Crypt::PKCS11::Attribute::RFC2279string

A base module that handles RFC 2279 string attributes.

=item Crypt::PKCS11::Attribute::UlongArray

A base module that handles unsigned long array attributes.

=item Crypt::PKCS11::Attribute::Value

A base module that handles attributes containing either a byte array or a binary
string.

=back

Following modules exist as an interface to its corresponding PKCS #11 C
structure, for more information about each structure see individual pod page and
PKCS #11 documentation.

=over 4

=item L<Crypt::PKCS11::CK_AES_CBC_ENCRYPT_DATA_PARAMS>

=item L<Crypt::PKCS11::CK_AES_CCM_PARAMS>

=item L<Crypt::PKCS11::CK_AES_CTR_PARAMS>

=item L<Crypt::PKCS11::CK_AES_GCM_PARAMS>

=item L<Crypt::PKCS11::CK_ARIA_CBC_ENCRYPT_DATA_PARAMS>

=item L<Crypt::PKCS11::CK_CAMELLIA_CBC_ENCRYPT_DATA_PARAMS>

=item L<Crypt::PKCS11::CK_CAMELLIA_CTR_PARAMS>

=item L<Crypt::PKCS11::CK_CMS_SIG_PARAMS>

=item L<Crypt::PKCS11::CK_DES_CBC_ENCRYPT_DATA_PARAMS>

=item L<Crypt::PKCS11::CK_ECDH1_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_ECDH2_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_ECMQV_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_KEA_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_KEY_DERIVATION_STRING_DATA>

=item L<Crypt::PKCS11::CK_KEY_WRAP_SET_OAEP_PARAMS>

=item L<Crypt::PKCS11::CK_KIP_PARAMS>

=item L<Crypt::PKCS11::CK_MECHANISM>

=item L<Crypt::PKCS11::CK_OTP_PARAM>

=item L<Crypt::PKCS11::CK_OTP_PARAMS>

=item L<Crypt::PKCS11::CK_OTP_SIGNATURE_INFO>

=item L<Crypt::PKCS11::CK_PBE_PARAMS>

=item L<Crypt::PKCS11::CK_PKCS5_PBKD2_PARAMS>

=item L<Crypt::PKCS11::CK_RC2_CBC_PARAMS>

=item L<Crypt::PKCS11::CK_RC2_MAC_GENERAL_PARAMS>

=item L<Crypt::PKCS11::CK_RC5_CBC_PARAMS>

=item L<Crypt::PKCS11::CK_RC5_MAC_GENERAL_PARAMS>

=item L<Crypt::PKCS11::CK_RC5_PARAMS>

=item L<Crypt::PKCS11::CK_RSA_PKCS_OAEP_PARAMS>

=item L<Crypt::PKCS11::CK_RSA_PKCS_PSS_PARAMS>

=item L<Crypt::PKCS11::CK_SKIPJACK_PRIVATE_WRAP_PARAMS>

=item L<Crypt::PKCS11::CK_SKIPJACK_RELAYX_PARAMS>

=item L<Crypt::PKCS11::CK_SSL3_KEY_MAT_OUT>

=item L<Crypt::PKCS11::CK_SSL3_KEY_MAT_PARAMS>

=item L<Crypt::PKCS11::CK_SSL3_MASTER_KEY_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_SSL3_RANDOM_DATA>

=item L<Crypt::PKCS11::CK_TLS_PRF_PARAMS>

=item L<Crypt::PKCS11::CK_VERSION>

=item L<Crypt::PKCS11::CK_WTLS_KEY_MAT_OUT>

=item L<Crypt::PKCS11::CK_WTLS_KEY_MAT_PARAMS>

=item L<Crypt::PKCS11::CK_WTLS_MASTER_KEY_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_WTLS_PRF_PARAMS>

=item L<Crypt::PKCS11::CK_WTLS_RANDOM_DATA>

=item L<Crypt::PKCS11::CK_X9_42_DH1_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_X9_42_DH2_DERIVE_PARAMS>

=item L<Crypt::PKCS11::CK_X9_42_MQV_DERIVE_PARAMS>

=back

=head1 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
{'fraction_non_alphanumeric': 0.12665457842248412, 'fraction_numerical': 0.042883046237534, 'mean_word_length': 5.413372093023256, 'pattern_counts': {'":': 0, '<': 50, '<?xml version=': 0, '>': 150, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '73107', 'n_tokens_mistral': 4269, 'n_tokens_neox': 3852, 'n_words': 960}