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

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

Closes a session

Parameters:h_session (int) – Session handle
Returns:retcode
Return type:int
pypkcs11.session_management.c_finalize()

Finalizes PKCS11 usage.

Returns:retcode
pypkcs11.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 ~pypkcs11.cryptoki.CK_VERSION structs, and the major/minor values can be accessed directly (info['cryptokiVersion'].major == 2)

Returns:(retcode, info dictionary)
pypkcs11.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
pypkcs11.session_management.c_get_slot_info(slot)

Get information about the given slot number.

Parameters:slot (int) – Target slot
Returns:Dictionary of slot information
pypkcs11.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
pypkcs11.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
pypkcs11.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
pypkcs11.session_management.c_initialize()

Initializes current process for use with PKCS11

Returns:retcode
pypkcs11.session_management.c_logout(h_session)

Logs out of a given session

Parameters:h_session (int) – Session handle
Returns:retcode
Return type:int
pypkcs11.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
pypkcs11.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
pypkcs11.session_management.get_firmware_version(slot)

Calls to C_GetTokenInfo for the given slot. Returns a string representing the firmware version.

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
pypkcs11.session_management.get_slot_dict(token_present=False)

Compiles a dictionary of the available slots

Returns:A python dictionary of the available slots
pypkcs11.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

Token Management

Created on Aug 24, 2012

@author: mhughes

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

Gets the list of mechanisms

Parameters:slot – The slot number to get the mechanism list on
Returns:The result code, A python dictionary representing the mechanism list
pypkcs11.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
pypkcs11.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