Session/Token Management¶
Modules for Token and session creation and management.
Session Management¶
Methods responsible for managing a user’s session and login/c_logout
-
pycryptoki.session_management.
c_initialize
(flags=None, init_struct=None)[source]¶ Initializes current process for use with PKCS11.
Some sample flags:
CKF_LIBRARY_CANT_CREATE_OS_THREADS CKF_OS_LOCKING_OKSee the PKCS11 documentation for more details.
Parameters: - flags (int) – Flags to be set within InitArgs Struct. (Default = None)
- init_struct – InitArgs structure (Default = None)
Returns: Cryptoki return code.
-
pycryptoki.session_management.
c_initialize_ex
(flags=None, init_struct=None)¶ Executes
c_initialize()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_finalize
()[source]¶ Finalizes PKCS11 library.
Returns: Cryptoki return code
-
pycryptoki.session_management.
c_finalize_ex
()¶ Executes
c_finalize()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_open_session
(slot_num, flags=6)[source]¶ Opens a session on the given slot
Parameters: Returns: (retcode, session handle)
Return type: tuple
-
pycryptoki.session_management.
c_open_session_ex
(slot_num, flags=6)¶ Executes
c_open_session()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
login
(h_session, slot_num=1, password=None, user_type=1)[source]¶ Login to the given session.
Parameters: Returns: retcode
Return type:
-
pycryptoki.session_management.
login_ex
(h_session, slot_num=1, password=None, user_type=1)¶ Executes
login()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_get_info
()[source]¶ Get general information about the Cryptoki Library
Returns a dictionary containing the following keys:
- cryptokiVersion
- manufacturerID
- flags
- libraryDescription
- libraryVersion
cryptokiVersion
andlibraryVersion
areCK_VERSION
structs, and the major/minor values can be accessed directly (info['cryptokiVersion'].major == 2
)Returns: (retcode, info dictionary)
-
pycryptoki.session_management.
c_get_info_ex
()¶ Executes
c_get_info()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_get_slot_list
(token_present=True)[source]¶ Get a list of all slots.
Parameters: token_present (bool) – If true, will only return slots that have a token present. Returns: List of slots
-
pycryptoki.session_management.
c_get_slot_list_ex
(token_present=True)¶ Executes
c_get_slot_list()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_get_slot_info
(slot)[source]¶ Get information about the given slot number.
Parameters: slot (int) – Target slot Returns: Dictionary of slot information
-
pycryptoki.session_management.
c_get_slot_info_ex
(slot)¶ Executes
c_get_slot_info()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_get_session_info
(session)[source]¶ Get information about the given session.
Parameters: session (int) – session handle Returns: (retcode, dictionary of session information) Return type: tuple
-
pycryptoki.session_management.
c_get_session_info_ex
(session)¶ Executes
c_get_session_info()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_get_token_info
(slot_id, rstrip=True)[source]¶ Gets the token info for a given slot id
Parameters: Returns: (retcode, A python dictionary representing the token info)
Return type: tuple
-
pycryptoki.session_management.
c_get_token_info_ex
(slot_id, rstrip=True)¶ Executes
c_get_token_info()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
get_slot_dict
(token_present=False)[source]¶ Compiles a dictionary of the available slots
Returns: A python dictionary of the available slots
-
pycryptoki.session_management.
get_slot_dict_ex
(token_present=False)¶ Executes
get_slot_dict()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_close_session
(h_session)[source]¶ Closes a session
Parameters: h_session (int) – Session handle Returns: retcode Return type: int
-
pycryptoki.session_management.
c_close_session_ex
(h_session)¶ Executes
c_close_session()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_logout
(h_session)[source]¶ Logs out of a given session
Parameters: h_session (int) – Session handle Returns: retcode Return type: int
-
pycryptoki.session_management.
c_logout_ex
(h_session)¶ Executes
c_logout()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_init_pin
(h_session, pin)[source]¶ Initializes the PIN
Parameters: - h_session (int) – Session handle
- pin – pin to c_initialize
Returns: THe result code
-
pycryptoki.session_management.
c_init_pin_ex
(h_session, pin)¶ Executes
c_init_pin()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
ca_factory_reset
(slot)[source]¶ Does a factory reset on a given slot
Parameters: slot – The slot to do a factory reset on Returns: The result code
-
pycryptoki.session_management.
ca_factory_reset_ex
(slot)¶ Executes
ca_factory_reset()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_set_pin
(h_session, old_pass, new_pass)[source]¶ Allows a user to change their PIN
Parameters: - h_session (int) – Session handle
- old_pass – The user’s old password
- new_pass – The user’s desired new password
Returns: The result code
-
pycryptoki.session_management.
c_set_pin_ex
(h_session, old_pass, new_pass)¶ Executes
c_set_pin()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
c_close_all_sessions
(slot)[source]¶ Closes all the sessions on a given slot
Parameters: slot – The slot to close all sessions on Returns: retcode Return type: int
-
pycryptoki.session_management.
c_close_all_sessions_ex
(slot)¶ Executes
c_close_all_sessions()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
ca_openapplicationID
(slot, id_high, id_low)[source]¶ Open an application ID on the given slot.
Parameters: Returns: retcode
Return type:
-
pycryptoki.session_management.
ca_openapplicationID_ex
(slot, id_high, id_low)¶ Executes
ca_openapplicationID()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
ca_closeapplicationID
(slot, id_high, id_low)[source]¶ Close a given AppID on a slot.
Parameters: Returns: retcode
Return type:
-
pycryptoki.session_management.
ca_closeapplicationID_ex
(slot, id_high, id_low)¶ Executes
ca_closeapplicationID()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
ca_setapplicationID
(id_high, id_low)[source]¶ Set the App ID for the current process.
Parameters: Returns: retcode
Return type:
-
pycryptoki.session_management.
ca_setapplicationID_ex
(id_high, id_low)¶ Executes
ca_setapplicationID()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
ca_restart_ex
(slot)¶ Executes
ca_restart()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.session_management.
get_firmware_version
(slot)[source]¶ Returns a string representing the firmware version of the given slot.
It will first try to call
CA_GetFirmwareVersion
, and if that fails (not present on older cryptoki libraries), will callC_GetTokenInfo
.Parameters: slot (int) – Token slot number Returns: Firmware String in the format “X.Y.Z”, where X is major, Y is minor, Z is subminor. Return type: str
Token Management¶
Created on Aug 24, 2012
@author: mhughes
-
pycryptoki.token_management.
c_init_token
(slot_num, password, token_label='Main Token')[source]¶ Initializes at token at a given slot with the proper password and label
Parameters: - slot_num – The index of the slot to c_initialize a token in
- password – The password to c_initialize the slot with
- token_label – The label to c_initialize the slot with (Default value = ‘Main Token’)
Returns: The result code
-
pycryptoki.token_management.
c_init_token_ex
(slot_num, password, token_label='Main Token')¶ Executes
c_init_token()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.token_management.
get_token_by_label
(label)[source]¶ Iterates through all the tokens and returns the first token that has a label that is identical to the one that is passed in
Parameters: label – The label of the token to search for Returns: The result code, The slot of the token
-
pycryptoki.token_management.
get_token_by_label_ex
(label)¶ Executes
get_token_by_label()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.token_management.
c_get_mechanism_list
(slot)[source]¶ Gets the list of mechanisms from the HSM
Parameters: slot – The slot number to get the mechanism list on Returns: The result code, A python dictionary representing the mechanism list
-
pycryptoki.token_management.
c_get_mechanism_list_ex
(slot)¶ Executes
c_get_mechanism_list()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.token_management.
c_get_mechanism_info
(slot, mechanism_type)[source]¶ Gets a mechanism’s info
Parameters: - slot – The slot to query
- mechanism_type – The type of the mechanism to get the information for
Returns: The result code, The mechanism info
-
pycryptoki.token_management.
c_get_mechanism_info_ex
(slot, mechanism_type)¶ Executes
c_get_mechanism_info()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)
-
pycryptoki.token_management.
ca_get_token_policies
(slot)[source]¶ Get the policies of the given slot.
Parameters: slot (int) – Target slot number Returns: retcode, {id: val} dict of policies (None if command failed)
-
pycryptoki.token_management.
ca_get_token_policies_ex
(slot)¶ Executes
ca_get_token_policies()
, and checks the retcode; raising an exception if the return code is not CKR_OK.Note
By default, this will not return the return code if the function returns additional data.
Example:
retcode, key_handle = c_generate_key(...) #vs key_handle = c_generate_key_ex(...)
If the function only returns the retcode, then that will still be returned:
retcode = c_seed_random(...) retcode = c_seed_random_ex(...)