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_close_all_sessions(slot)

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.c_close_session(h_session)

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_finalize()

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_get_info()

Get general information about the Cryptoki Library

Returns a dictionary containing the following keys:

• cryptokiVersion
• manufacturerID
• flags
• libraryDescription
• libraryVersion

cryptokiVersion and libraryVersion are ~pycryptoki.cryptoki.CK_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_session_info(session)

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_slot_info(slot)

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_slot_list(token_present=True)

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_token_info(slot_id, rstrip=True)

Gets the token info for a given slot id

Parameters:

• slot_id (int) – Token slot ID
• rstrip (bool) – If true, will strip trailing whitespace from char data.

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.c_init_pin(h_session, pin)

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.c_initialize(flags=None, init_struct=None)

Initializes current process for use with PKCS11.

Some sample flags:

CKF_LIBRARY_CANT_CREATE_OS_THREADS CKF_OS_LOCKING_OK

See 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_logout(h_session)

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_open_session(slot_num, flags=6)

Opens a session on the given slot

Parameters:

• slot_num (int) – The slot to get a session on
• flags (int) – The flags to open the session with (Default value = (CKF_SERIAL_SESSION | CKF_RW_SESSION)

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.c_set_pin(h_session, old_pass, new_pass)

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.ca_closeapplicationID(slot, id_high, id_low)

Close a given AppID on a slot.

Parameters:

• slot (int) – Slot on which to close the APP ID
• id_high (int) – High value of App ID
• id_low (int) – Low value of App ID

Returns:

retcode

Return type:

int

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_factory_reset(slot)

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.ca_openapplicationID(slot, id_high, id_low)

Open an application ID on the given slot.

Parameters:

• slot (int) – Slot on which to open the APP ID
• id_high (int) – High value of App ID
• id_low (int) – Low value of App ID

Returns:

retcode

Return type:

int

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_restart(slot)

Parameters:slot –

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.ca_setapplicationID(id_high, id_low)

Set the App ID for the current process.

Parameters:

• id_high (int) – High value of App ID
• id_low (int) – Low value of App ID

Returns:

retcode

Return type:

int

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.get_firmware_version(slot)

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 call C_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

pycryptoki.session_management.get_slot_dict(token_present=False)

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.login(h_session, slot_num=1, password=None, user_type=1)

Login to the given session.

Parameters:

• h_session (int) – Session handle
• slot_num (int) – Slot index to login on (Default value = 1)
• password (bytes) – Password to login with (Default value = “userpin”)
• user_type (int) – User type to login as (Default value = 1)

Returns:

retcode

Return type:

int

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(...)

Token Management

Created on Aug 24, 2012

@author: mhughes

pycryptoki.token_management.c_get_mechanism_info(slot, mechanism_type)

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.c_get_mechanism_list(slot)

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_init_token(slot_num, password, token_label='Main Token')

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.ca_get_token_policies(slot)

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(...)

pycryptoki.token_management.get_token_by_label(label)

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(...)