Crypt::PKCS11::Session - PKCS #11 session handler.
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, log in, use the session, log out and close the session my $session = $pkcs11->OpenSession(...); $session->Login(...); ... $session->Logout; $session->CloseSession;
This module encapsulates the PKCS #11 session created with Crypt::PKCS11-OpenSession> and is used to manage the keys and encrypt/decrypt data using a HSM.
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.
$pkcs11->errno
$pkcs11->errstr
For errors from the methods themself, the method will confess (croak) with the error message.
For more extensive documentation about the methods, data structures and types please see http://www.cryptsoft.com/pkcs11doc/v230/ .
Initializes the normal user's PIN.
The argument is optional due to "protected authentication path", please see the PKCS #11 documentation for more information about that.
Optional argument that is the normal user's PIN, if given must contain a number or a non-empty string.
Modifies the PIN of the user that is currently logged in, or the CKU_USER PIN if the session is not logged in.
CKU_USER
The arguments are optional due to "protected authentication path", please see the PKCS #11 documentation for more information about that.
Optional argument that is the user's old PIN, if given must contain a number or a non-empty string.
Optional argument that is the user's new PIN, if given must contain a number or a non-empty string.
Close the session, any use of the object after closing the session will result in an error.
Return information about the session as a hash, if called in list context, or as a hash reference, if called in scalar context.
Fields in hash are as follows:
ID of the slot that interfaces with the token.
The state of the session.
Bit flags that define the type of session.
An error code defined by the cryptographic device. Used for errors not covered by Cryptoki.
Obtains a copy of the cryptographic operations state of a session, encoded as a string of bytes.
Restores the cryptographic operations state of a session from a string of bytes obtained with C_GetOperationState.
The saved state.
Optional argument with the key which will be used for an ongoing encryption or decryption operation in the restored session (or undef if no encryption or decryption key is needed, either because no such operation is ongoing in the stored session or because all the necessary key information is present in the saved state).
Optional argument with the key which will be used for an ongoing signature, MACing, or verification operation in the restored session (or undef if no such key is needed, either because no such operation is ongoing in the stored session or because all the necessary key information is present in the saved state).
Logs a user into a token.
The user type.
Optional argument with the user's PIN.
Logs a user out from a token.
Creates a new object, returns a Crypt::PKCS11::Object when successful.
A Crypt::PKCS11::Attributes containing the object's template.
Copies an object, creating a new object for the copy. Returns a Crypt::PKCS11::Object when successful.
A Crypt::PKCS11::Object with the object to copy.
A Crypt::PKCS11::Attributes containing the new object's template.
Destroys an object.
A Crypt::PKCS11::Object with the object to destroy.
Gets the size of an object in bytes.
A Crypt::PKCS11::Object with the object.
Obtains the value of one or more attributes of an object. Returns a list of Crypt::PKCS11::Attribute objects with the attributes retrieved, if called in list context, otherwise the normal return statuses are used and the retrieved attributes are contained with the template.
A Crypt::PKCS11::Attributes containing the attributes to retrieve.
Modifies the value of one or more attributes of an object.
A Crypt::PKCS11::Attributes containing the attributes to modify.
Initializes a search for token and session objects that match a template.
A Crypt::PKCS11::Attributes containing the template.
Start or continues a search for token and session objects that match a template. Returns a list of Crypt::PKCS11::Object objects, if called in list context, or as an array reference, if called in scalar context.
The maximum number of objects to be returned.
Terminates a search for token and session objects.
Initializes an encryption operation.
A Crypt::PKCS11::CK_MECHANISM with the encryption mechanism.
A Crypt::PKCS11::Object to use as the encryption key.
Encrypts single-part data. Returns the encrypted data on success.
The data to encrypt.
Continues a multiple-part encryption operation, processing another data part. Returns the encrypted data part on success.
The data part to encrypt.
Finishes a multiple-part encryption operation. Returns the last encrypted data part, if any.
Initializes a decryption operation.
A Crypt::PKCS11::CK_MECHANISM with the decryption mechanism.
A Crypt::PKCS11::Object to use as the decryption key.
Decrypts encrypted data in a single part. Returns the decrypted data on success.
The encrypted data to decrypt.
Continues a multiple-part decryption operation, processing another encrypted data part. Returns the decrypted data part on success.
The encrypted data part to decrypt.
Finishes a multiple-part decryption operation. Returns the last recovered data part, if any.
Initializes a message-digesting operation.
A Crypt::PKCS11::CK_MECHANISM with the digesting mechanism.
Digests data in a single part. Returns the message digest on success.
The data to digest.
Continues a multiple-part message-digesting operation, processing another data part. Returns the message digest part on success.
The data part to digest.
Continues a multiple-part message-digesting operation by digesting the value of a secret key.
A Crypt::PKCS11::Object with the secret key to be digested.
Finishes a multiple-part message-digesting operation, returning the message digest.
Initializes a signature operation, where the signature is an appendix to the data.
A Crypt::PKCS11::CK_MECHANISM with the signature mechanism.
A Crypt::PKCS11::Object to use as the signature key.
Signs data in a single part, where the signature is an appendix to the data. Returns the signature on success.
The data to sign.
Continues a multiple-part signature operation, processing another data part.
The data part to sign.
Finishes a multiple-part signature operation, returning the signature.
Initializes a signature operation, where the data can be recovered from the signature.
Signs data in a single operation, where the data can be recovered from the signature. Returns the signature on success.
Initializes a verification operation, where the signature is an appendix to the data.
A Crypt::PKCS11::CK_MECHANISM with the verification mechanism.
A Crypt::PKCS11::Object to use as the verification key.
Verifies a signature in a single-part operation, where the signature is an appendix to the data.
The data to verify.
The signature to verify.
Continues a multiple-part verification operation, processing another data part.
The data part to verify.
Finishes a multiple-part verification operation, checking the signature.
Initializes a signature verification operation, where the data is recovered from the signature.
Verifies a signature in a single-part operation, where the data is recovered from the signature. Returns the data on success.
Continues multiple-part digest and encryption operations, processing another data part. Returns the encrypted data part on success.
The data part.
Continues a multiple-part combined decryption and digest operation, processing another data part. Returns the data part on success.
The encrypted data part.
Continues a multiple-part combined signature and encryption operation, processing another data part. Returns the encrypted data part on success.
Continues a multiple-part combined decryption and verification operation, processing another data part. Returns the data part on success.
Generates a secret key or set of domain parameters, creating a new object. Returns a Crypt::PKCS11::Object on success.
A Crypt::PKCS11::CK_MECHANISM with the generation mechanism.
A Crypt::PKCS11::Attributes containing the template for the new key or set of domain parameters.
Generates a public/private key pair, creating new key objects. Return both keys on success.
A Crypt::PKCS11::Attributes containing the template for the public key.
A Crypt::PKCS11::Attributes containing the template for the private key.
Wraps (i.e., encrypts) a private or secret key. Returns the wrapped key on success.
A Crypt::PKCS11::CK_MECHANISM with the wrapping mechanism.
A Crypt::PKCS11::Object with the wrapping key.
A Crypt::PKCS11::Object with the key to be wrapped.
Unwraps (i.e. decrypts) a wrapped key, creating a new private key or secret key object. Returns a Crypt::PKCS11::Object on success.
A Crypt::PKCS11::CK_MECHANISM with the unwrapping mechanism.
A Crypt::PKCS11::Object with the unwrapping key.
The wrapped key.
A Crypt::PKCS11::Attributes containing the template for the new key.
Derives a key from a base key, creating a new key object. Returns a Crypt::PKCS11::Object on success.
A Crypt::PKCS11::CK_MECHANISM with the derivation mechanism.
A Crypt::PKCS11::Object with the base key.
Mixes additional seed material into the token's random number generator.
The seed material.
Generates random or pseudo-random data. Returns the random or pseudo-random data on success.
The length in bytes of the random or pseudo-random data to be generated.
Obtained the status of a function running in parallel with an application. Will always return the CKR from the C layer function.
Cancelled a function running in parallel with an application. Will always return the CKR from the C layer function.
Return the last error number, can be used after a method returns false.
Return the last error message, can be used after a method returns false.
These are the private methods used within the module and should not be used elsewhere.
Derived from the RSA Security Inc. PKCS #11 Cryptographic Token Interface (Cryptoki)
Jerry Lundström <lundstrom.jerry@gmail.com>
Report bugs at https://github.com/dotse/p5-Crypt-PKCS11/issues .
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.