Global Platform functions¶

auth(enc_key=None, mac_key=None, dek_key=None, scp=None, scpi=None, keysetversion='21', sequence_counter='000000', securitylevel=0)¶

Performs a complete authentication with the card using the specifiied key set, secure channel protocol,and security level for secure messaging.

Parameters:

enc_key (str) – The Session Encryption Key. If None (default) the off card repository key with the specified keyset number is used.
mac_key (str) – The Secure Channel Message Authentication Code Key. If None (default) the off card repository key with the specified keyset number is used.
dek_key (str) – The Key Encryption Key. If None (default) the off card repository key with the specified keyset number is used.
scp (str) – The Session Channel Protocol to used. If None (default) the SCP returned by the card is used.
scpi (str) – The Secure Channel Protocol Implementation to used. If None (default) the SCP implementation returned by the card is used.
keysetversion (str) – The Key Set version to used.
sequence_counter (str) – The current sequence counter. Use only in case of payload mode.
securitylevel (int) –
The security level of the secure messaging. Could be:
- SECURITY_LEVEL_NO_SECURE_MESSAGING (0x00): No secure messaging expected.
- SECURITY_LEVEL_C_MAC (0x01): C-MAC.
- SECURITY_LEVEL_C_DEC_C_MAC (0x03): C-DECRYPTION and C-MAC.
- SECURITY_LEVEL_R_MAC (0x10): R-MAC.
- SECURITY_LEVEL_C_MAC_R_MAC (0x11): C-MAC and R-MAC.
- SECURITY_LEVEL_C_DEC_C_MAC_R_MAC (0x13): C-DECRYPTION, C-MAC and R-MAC.
- SECURITY_LEVEL_C_DEC_R_ENC_C_MAC_R_MAC (0x33): C-Decryption, C-MAC, R-Mac and R-Encryption.

Note

Depending of SCP mode used, some security level will not be available.

channel(logical_channel=None)¶

Selects the logical channel to use.

Parameters:	logical_channel (int) – The Logical Channel number (0..3) to select.

Note

You must track on your own, what channels are opened.

delete(aid, exsw=None)¶

Performs an application deletion by its AID.

Parameters:	aid (str) – The AID of the application to delete. exsw (str) – Set expected Status word.

delete_key(key_version_number, key_identifier, exsw=None)¶

Performs a key deletion identifies by its version number and its key identifier.

Parameters:	key_version_number (str) – The key version number. key_identifier (str) – The key identifier. exsw (str) – Set expected Status word.

Note

The key is not deleted into the the off card key repository.

delete_package(aid, exsw=None)¶

Performs a package and related application deletion by its AID.

Parameters:	aid (str) – The AID of the package to delete. exsw (str) – Set expected Status word.

extradite(security_domain_AID, application_aid, identification_number=None, image_Number=None, application_provider_identifier=None, token_identifier=None, extraditeToken=None)¶

Performs an application extradition into a Security Domain.

Parameters:

security_domain_AID (str) – The AID of the Security domain.
application_aid (str) – The AID of the application to extradite.
identification_number (str) – The Identification Number of the Security Domain with the Token Verification privilege.
image_Number (str) – The Image Number of the Security Domain with the Token Verification privilege.
application_provider_identifier (str) – The Application Provider identifier.
token_identifier (str) – The Token identifier/number (digital signature counter).
extraditeToken (str) – The extradition token (None by default).

ext_auth(hostCryptogram, securitylevel=0)¶

Performs an external authenticate using the specifiied cryptogram and security level to use during secure messaging.

Parameters:

hostCryptogram (str) – The off card host cryptogram retreived during the init_update() command.
securitylevel (int) –
The security level of the secure messaging. Could be:
- SECURITY_LEVEL_NO_SECURE_MESSAGING (0x00): No secure messaging expected.
- SECURITY_LEVEL_C_MAC (0x01): C-MAC.
- SECURITY_LEVEL_C_DEC_C_MAC (0x03): C-DECRYPTION and C-MAC.
- SECURITY_LEVEL_R_MAC (0x10): R-MAC.
- SECURITY_LEVEL_C_MAC_R_MAC (0x11): C-MAC and R-MAC.
- SECURITY_LEVEL_C_DEC_C_MAC_R_MAC (0x13): C-DECRYPTION, C-MAC and R-MAC.
- SECURITY_LEVEL_C_DEC_R_ENC_C_MAC_R_MAC (0x33): C-Decryption, C-MAC, R-Mac and R-Encryption.

Note

Depending of SCP mode used during the init_update(), some security level will not be available.

get_certificate(key_version_number, key_identifier)¶

Retrieves a CERT.SD.ECKA from the SD.

Returns str data_response:
Parameters:	key_version_number (str) – the key set version. key_identifier (str) – the key identifier.
	The response data containing the certificate.

get_cplc()¶: Get Card Production life cycle data and log it through the logger.

get_crs_status(aid=None, tag_list=None)¶

Retrieves the CRS registered Contactless Applications display information, the Lifecycle status and other information according to the given match/search criteria.

Parameters:	aid (str) – search criterion AID, if empty it will search previously selected CRS Application recursively. tag_list (str) – Indicates to the CRS Application how to construct the response data for matching search criteria.

get_data(identifier)¶

Retrieves a single card data object from the card identified by identifier. Some cards do not provide some data objects. Some possible identifiers are predefined. There is a convenience method get_key_information() to get the key information containing key set version, key index, key type and key length of the keys.

Parameters:	identifier (str) – the Two byte string with high and low order tag value for identifying card data object.

get_key_information()¶: Get key information for the currently selected Application and log it through the logger.

get_status_isd()¶: Get the AID, the life cycle state and the privileges of the Issuer Security Domain and log it through the logger.

get_status_applications()¶: Get the AID, the life cycle state and the privileges of all applications and log it through the logger.

get_status_executable_load_files()¶: Get the AID and the life cycle state of all executable load files and log it through the logger.

get_status_executable_load_files_and_modules()¶: Get the AID, the life cycle state and the modules AID of all executable load file and modules and then log it through the logger.

init_update(enc_key=None, mac_key=None, dek_key=None, scp=None, scpi=None, keysetversion='21', sequence_counter='000000')¶

Performs an initialize update using specifiied key set and secure channel protocol.

Parameters:

enc_key (str) – The Session Encryption Key. If None (default) the off card repository key with the specified keyset number is used.
mac_key (str) – The Secure Channel Message Authentication Code Key. If None (default) the off card repository key with the specified keyset number is used.
dek_key (str) – The Key Encryption Key. If None (default) the off card repository key with the specified keyset number is used.
scp (str) – The Session Channel Protocol to used. If None (default) the SCP returned by the card is used.
scpi (str) – The Secure Channel Protocol Implementation to used. If None (default) the SCP implementation returned by the card is used.
keysetversion (str) – The Key Set version to used.
sequence_counter (str) – The current sequence counter. Use only in case of payload mode.

Returns str hostCryptogram:

The off card host cryptogram to use into the ext_auth() function.

install(make_selectable, executable_LoadFile_AID, executable_Module_AID, application_AID, application_privileges=[], application_specific_parameters=None, install_parameters=None, install_token=None)¶

Performs an install for install of an application into a Security Domain.

Parameters:

make_selectable (boolean) – True if the application must be selectable.
executable_LoadFile_AID (str) – The AID of the load file package.
executable_Module_AID (str) – The AID of the load file module.
application_AID (str) – The AID of the application instance.
application_privileges (str) – A list of Application privileges for the Application ([] by default).
application_specific_parameters (str) – The application parameters (under tag C9)
install_parameters (str) – The installation parameter (under tag EF).
install_token (str) – The install token (None by default).

Note

example of application_privileges parameter : [“SD”, “TP”] means privilege Security Domain with Trusted Path

install_load(load_file_path, security_domain_aid, load_file_data_block_hash=None, load_parameters=None, load_token=None)¶

Performs an install for load of a load file into a Security Domain.

Parameters:

load_file_path (str) – The path of the load file to install.
security_domain_aid (str) – The AID of the Security domain.
load_file_data_block_hash (str) – Mandatory if a Load Token is present or if the Load File contains one or more DAP Blocks.
load_parameters (str) – The load file parameter (under tag EF, None by default).
load_token (str) – The load token (None by default).

internal_auth(key_version_number, key_identifier, crt_data, ePK_OCE_ECKA)¶

Performs an internal authenticate command using the specified parameters.

Returns str data_response:
Parameters:	key_version_number (str) – the key set version. key_identifier (str) – the key identifier. crt_data (str) – The data for key establishment. ePK_OCE_ECKA (str) – The Ephemeral public key of the OCE used for key agreement
	The response data containing the Ephemeral public key of the SD used for key agreement and the receipt.

load_file(load_file_path, block_size=230)¶

Performs a set of load commands using the load file parameter.

Parameters:	load_file_path (str) – The path of the load file to load. block_size (int) – The size of the data blocks.

ls()¶: Get the status of all executable load file, modules and applications and then log it through the logger.

manage_channel(open_channel, logical_channel=None)¶

Uses to open or close supplementaty logical channels.

Parameters:	open_channel (boolean) – wether open/close the channel. True means to open and False to close the channel. logical_channel (int) – The Logical channel number (0..3) to open/close.

mutual_auth(key_version_number, key_identifier, crt_data, ePK_OCE_ECKA)¶

Performs an mutual authenticate command using the specified parameters.

Returns str data_response:
Parameters:	key_version_number (str) – the key set version. key_identifier (str) – the key identifier. crt_data (str) – The data for key establishment. ePK_OCE_ECKA (str) – The Ephemeral public key of the OCE used for key agreement
	The response data containing the Ephemeral public key of the SD used for key agreement and the receipt.

perform_security_operation(key_version_number, key_identifier, certificate)¶

The PERFORM SECURITY OPERATION command is used to send the OCE certificate to the SD. This is required as a precondition to the initiation of an SCP11 secure channel.

Parameters:	key_version_number (str) – the key set version. key_identifier (str) – the key identifier. certificate (str) – The certificate data.

put_key(key_version_number, key_identifier=None, replace=False)¶

Add or replace a new key identified by its version number and key identifier.

Parameters:	key_version_number (str) – The key version number. key_identifier (str) – The key identifier. replace (bool) – True if the key must be replaced, False otherwise.

Note

The key must be presented in the the off card key repository before set it into the card. see set_key()

put_scp_key(key_version_number, replace=False)¶

Add or replace scp keys identified by its version number.

Parameters:	key_version_number (str) – The key version number. replace (bool) – True if the key must be replaced, False otherwise.

Note

The key must be present in the the off card key repository before set it into the card. see set_key()

registry_update(security_domain_AID, application_aid, application_privileges=[], registry_parameter_field=None, install_token=None)¶

Performs an install for registry update of an application into a Security Domain.

Parameters:	security_domain_AID (str) – The AID of the security domain. application_AID (str) – The AID of the application instance. application_privileges (str) – A list of Application privileges for the Application ([] by default). registry_parameter_field (str) – The application parameters (under tag EF) install_token (str) – The install token (None by default).

Note

example of application_privileges parameter : [“SD”, “TP”] means privilege Security Domain with Trusted Path

select(aid, channel=0)¶

Performs an application selection by its AID.

Parameters:	aid (str) – The AID of the application to select channel (int) – The logical channel number. If None (default) channel number 00 will be used.

select_isd(channel=0)¶: Select the Issuer Security Domain using select by default APDU command. :param int channel: The logical channel number. If None (default) channel number 00 will be used.

send(apdu, raw_mode=False, exsw=None, exdata=None)¶

Sends an APDU Command according to the security level of the selected Security Domain

Parameters:	apdu (str) – The apdu command. raw_mode (bool) – If True apdu is sent without security level management. exsw (str) – Set expected Status word. exsw=”6A88, 6982”. There should be ‘,’ as delimiter exdata (str) – Set expected response data. It compare R-APDU with response data.

set_sd_state(lifeCycleState, aid)¶

Modifies the security domain Life Cycle State.

Parameters:	lifeCycleState (str) – The new life cycle state. aid (str) – the AID of the target Application or Security Domain for which a Life Cycle change is requested.

set_app_state(lifeCycleState, aid)¶

Modifies the Application Life Cycle State.

Parameters:	lifeCycleState (str) – The new life cycle state. aid (str) – the AID of the target Application or Security Domain for which a Life Cycle change is requested.

set_crs_status(status_type, status_value, aid)¶

Modifies the card Life Cycle State or the Application Life Cycle State.

Parameters:	status_type (str) – Type of information shall be updated. (i.e. availability, priority order, etc.) status_value (str) – Updating value depends on the status type in ‘status_type’ aid (str) – the AID of the target CRS Application.

set_status(cardElement, lifeCycleState, aid)¶

Modifies the card Life Cycle State or the Application Life Cycle State.

Parameters:	cardElement (str) – Identifier for Load Files, Applications or the Card Manager.See constants values in Set_Status Reference Control Parameter P1. lifeCycleState (str) – The new life cycle state. aid (str) – the AID of the target Application or Security Domain for which a Life Cycle change is requested.

store_data(data)¶

Allows to transfer data to an Application or Security Domain processing the command. Depending of the data length, Multiple STORE DATA commands are used to send data to the Application or Security Domain by breaking the data into smaller components for transmission.

Parameters:	data (str) – data in a format expected by the Security Domain or the Application.

upload(load_file_path, security_domain_aid)¶

Performs a load of an application under the Security Domain

Parameters:	load_file_path (str) – The path of the load file to load. security_domain_aid (str) – The AID of the Security Domain.

Note

The install for install command is not send by this function.

upload_install(load_file_path, security_domain_aid, executable_module_aid, application_aid)¶

Performs a full load of an application under the selected Security Domain

Parameters:	load_file_path (str) – The path of the load file to load. executable_LoadFile_AID (str) – The AID of the load file package. executable_Module_AID (str) – The AID of the load file module. application_AID (str) – The AID of the application instance.