Extensions to the PKCS11 API

Thales-specific Extensions to the PKCS11 API.

Derive Key And Wrap

derive and wrap extended method

pycryptoki.ca_extensions.derive_wrap.ca_derive_key_and_wrap(h_session, derive_mechanism, h_base_key, derive_template, wrapping_key, wrap_mechanism, output_buffer=2048)[source]

Derive a key from the base key and wrap it off the HSM using the wrapping key

Parameters:
  • h_session (int) – The session to use
  • h_base_key (int) – The base key
  • derive_template (dict) – A python template of attributes to set on derived key
  • derive_mechanism – See the parse_mechanism() function for possible values.
  • wrapping_key (int) – The wrapping key based on the encryption flavor
  • wrap_mechanism – See the parse_mechanism() function for possible values.
  • output_buffer – The size of the wrapped key, defaulted to a cert size
Returns:

(Retcode, python bytestring representing wrapped key)
Return type:

tuple
pycryptoki.ca_extensions.derive_wrap.ca_derive_key_and_wrap_ex(h_session, derive_mechanism, h_base_key, derive_template, wrapping_key, wrap_mechanism, output_buffer=2048)

Executes ca_derive_key_and_wrap(), 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(...)

HSM Info

Methods responsible for retrieving hsm info from the K7 card

pycryptoki.ca_extensions.hsm_info.ca_retrieve_license_list(slot)[source]

Gets the license info for a given slot id

Parameters:slot_id (int) – Slot index to get the license id’s
Returns:(A python list representing the license id’s)
Return type:list
pycryptoki.ca_extensions.hsm_info.ca_retrieve_license_list_ex(slot)

Executes ca_retrieve_license_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.ca_extensions.hsm_info.ca_retrieve_allowed_containers(slot)[source]

Gets the maximum allowed container number for a given slot id

Parameters:slot_id (int) – Slot index to get the maximum allowed container number
Returns:(ret code, A unsigned integer representing the maximum allowed container number)
Return type:unsigned integer
pycryptoki.ca_extensions.hsm_info.ca_retrieve_allowed_containers_ex(slot)

Executes ca_retrieve_allowed_containers(), 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.ca_extensions.hsm_info.ca_retrieve_hsm_storage_info(slot)[source]

Gets the hsm storage info for a given slot id

Parameters:slot_id (int) – Slot index to get the hsm storage info
Returns:(ret code, hsm_storage_info dictionary)
Return type:dictionary
pycryptoki.ca_extensions.hsm_info.ca_retrieve_hsm_storage_info_ex(slot)

Executes ca_retrieve_hsm_storage_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.ca_extensions.hsm_info.ca_get_tsv(slot)[source]

Get the TSV(Module State Vector) for a given slot id

Parameters:slot_id (int) – Slot index to get the TSV(Module State Vector)
Returns:(ret code, TSV)
Return type:tuple
pycryptoki.ca_extensions.hsm_info.ca_get_tsv_ex(slot)

Executes ca_get_tsv(), 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.ca_extensions.hsm_info.ca_get_cv_firmware_version(slot_id)[source]

Cryptovisor specific ca extension function to get cv fw version

Parameters:slot_id – slot id
Returns:tuple of return code and cv fw version
pycryptoki.ca_extensions.hsm_info.ca_get_cv_firmware_version_ex(slot_id)

Executes ca_get_cv_firmware_version(), 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(...)

Object Commands

Module to work with objects, specifically dealing with ca_extension functions

pycryptoki.ca_extensions.object_handler.ca_get_object_handle(slot, session, objectouid)[source]

Calls CA_GetObjectHandle to get the object handle from OUID

Parameters:
  • slot – partition slot number
  • session – session id that was opened to run the function
  • objectouid – OUID, a string of the hex value that maps to object handle
Returns:

a tuple containing the return code and the object handle mapping the given OUID
pycryptoki.ca_extensions.object_handler.ca_get_object_handle_ex(slot, session, objectouid)

Executes ca_get_object_handle(), 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.ca_extensions.object_handler.ca_destroy_multiple_objects(h_session, objects)[source]

Delete multiple objects corresponding to given object handles

Parameters:
  • h_session (int) – Session handle
  • objects (list) – The handles of the objects to delete
Returns:

Return code
pycryptoki.ca_extensions.object_handler.ca_destroy_multiple_objects_ex(h_session, objects)

Executes ca_destroy_multiple_objects(), 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(...)

Per Key Authorization

Module to work with PKA / Per key authorization

pycryptoki.ca_extensions.per_key_auth.ca_set_authorization_data(h_session, h_object, old_auth_data, new_auth_data)[source]

User changes authorization data on key object (private, secret)

Parameters:
  • h_session – session handle
  • object – key handle to update
  • old_auth_data – byte list, e.g. [11, 12, 13, ..]
  • new_auth_data – byte list, e.g. [11, 12, 13, ..]
Returns:

Ret code
pycryptoki.ca_extensions.per_key_auth.ca_set_authorization_data_ex(h_session, h_object, old_auth_data, new_auth_data)

Executes ca_set_authorization_data(), 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.ca_extensions.per_key_auth.ca_reset_authorization_data(h_session, h_object, auth_data)[source]

CO resets auth data on unassigned key

Parameters:
  • h_session – session handle
  • object – key handle to update
  • auth_data – byte list, e.g. [11, 12, 13, ..]
Returns:

Ret code
pycryptoki.ca_extensions.per_key_auth.ca_reset_authorization_data_ex(h_session, h_object, auth_data)

Executes ca_reset_authorization_data(), 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.ca_extensions.per_key_auth.ca_increment_failed_auth_count(h_session, h_object)[source]

This function is called by HA group when auth failure happens on a key to sync up status. Here its defined mostly for testing purposes :param h_session: session handle :param object: key handle to update :return: Ret code

pycryptoki.ca_extensions.per_key_auth.ca_increment_failed_auth_count_ex(h_session, h_object)

Executes ca_increment_failed_auth_count(), 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.ca_extensions.per_key_auth.ca_authorize_key(h_session, h_object, auth_data)[source]

User authorizes key within session or access for use

Parameters:
  • h_session – session handle
  • object – key handle to authorize
  • auth_data – authorization byte list, e.g. [11, 12, 13, ..]
Returns:

Ret code
pycryptoki.ca_extensions.per_key_auth.ca_authorize_key_ex(h_session, h_object, auth_data)

Executes ca_authorize_key(), 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.ca_extensions.per_key_auth.ca_assign_key(h_session, h_object)[source]

Crypto Officer assigns a key

Parameters:
  • h_session – session handle
  • object – key handle to assign
Returns:

Ret code
pycryptoki.ca_extensions.per_key_auth.ca_assign_key_ex(h_session, h_object)

Executes ca_assign_key(), 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(...)

Session Commands

Module to work with sessions, specifically dealing with ca_extension functions

pycryptoki.ca_extensions.session.ca_get_session_info(session)[source]

ca extension function that returns session information

Parameters:session – session handle
Returns:tuple of return code and session info dict
pycryptoki.ca_extensions.session.ca_get_session_info_ex(session)

Executes ca_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.ca_extensions.session.ca_get_application_id()[source]

Get the current process’s AccessID.

Returns:retcode, bytestring tuple.
pycryptoki.ca_extensions.session.ca_get_application_id_ex()

Executes ca_get_application_id(), 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.ca_extensions.session.ca_open_application_id_v2(slot, appid)[source]

Open the given AccessID for the target slot.

Parameters:
  • slot – Slot #.
  • appid – bytestring of length 16.
Returns:

Retcode.
pycryptoki.ca_extensions.session.ca_open_application_id_v2_ex(slot, appid)

Executes ca_open_application_id_v2(), 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.ca_extensions.session.ca_close_application_id_v2(slot, appid)[source]

Close the AccessID associated with the given slot.

Parameters:
  • slot – Slot #.
  • appid – bytestring of length 16.
Returns:

Retcode.
pycryptoki.ca_extensions.session.ca_close_application_id_v2_ex(slot, appid)

Executes ca_close_application_id_v2(), 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.ca_extensions.session.ca_set_application_id_v2(appid)[source]

Set the Current process’s AccessID.

Parameters:appid – bytestring of length 16
Returns:Retcode
pycryptoki.ca_extensions.session.ca_set_application_id_v2_ex(appid)

Executes ca_set_application_id_v2(), 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(...)

Utilization Metrics

Module to work with utilization metrics

pycryptoki.ca_extensions.utilization_metrics.ca_read_utilization_metrics(session)[source]

HSM reads utilization data and saves as a snapshot

Parameters:session – session id that was opened to run the function
Returns:Ret code
pycryptoki.ca_extensions.utilization_metrics.ca_read_utilization_metrics_ex(session)

Executes ca_read_utilization_metrics(), 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.ca_extensions.utilization_metrics.ca_read_and_reset_utilization_metrics(session)[source]

HSM reads current utilization data and saves as a snapshot; HSM resets metrics to zeroes

Parameters:session – session id that was opened to run the function
Returns:a dictionary with partition serial numbers as keys, value - dictionary of utilization metrics
pycryptoki.ca_extensions.utilization_metrics.ca_read_and_reset_utilization_metrics_ex(session)

Executes ca_read_and_reset_utilization_metrics(), 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.ca_extensions.utilization_metrics.ca_read_all_utilization_counters(h_session)[source]

Read Metrics from previously saved HSM snapshot Call either functions prior to create snapshot: ca_read_utilization_metrics ca_read_and_reset_utilization_metrics

Returns:a dictionary, where keys are serial numbers

and values are dictionaries of bins and values, example: ‘SIGN’:0

pycryptoki.ca_extensions.utilization_metrics.ca_read_all_utilization_counters_ex(h_session)

Executes ca_read_all_utilization_counters(), 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(...)