LIBRARY

Mifare card manipulation library (libfreefare, -lfreefare)

SYNOPSIS

In freefare.h Ft int Fn mifare_desfire_connect MifareTag tag Ft int Fn mifare_desfire_disconnect MifareTag tag Ft int Fn mifare_desfire_authenticate MifareTag tag uint8_t key_no MifareDESFireKey key Ft int Fn mifare_desfire_authenticate_aes MifareTag tag uint8_t key_no MifareDESFireKey key Ft int Fn mifare_desfire_authenticate_iso MifareTag tag uint8_t key_no MifareDESFireKey key Ft int Fn mifare_desfire_change_key_settings MifareTag tag uint8_t settings Ft int Fn mifare_desfire_get_key_settings MifareTag tag uint8_t *settings uint8_t *max_keys Ft int Fn mifare_desfire_change_key MifareTag tag uint8_t key_no MifareDESFireKey new_key MifareDESFireKey old_key Ft int Fn mifare_desfire_get_key_version MifareTag tag uint8_t key_no uint8_t *version Ft int Fn mifare_desfire_create_application MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no Ft int Fn mifare_desfire_create_application_aes MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no Ft int Fn mifare_desfire_create_application_3k3des MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no Ft int Fn mifare_desfire_create_application_iso MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no int want_iso_file_identifiers uint16_t iso_file_id uint8_t *iso_file_name size_t iso_file_name_len Ft int Fn mifare_desfire_create_application_3k3des_iso MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no int want_iso_file_identifiers uint16_t iso_file_id uint8_t *iso_file_name size_t iso_file_name_len Ft int Fn mifare_desfire_create_application_aes_iso MifareTag tag MifareDESFireAID aid uint8_t settings uint8_t key_no int want_iso_file_identifiers uint16_t iso_file_id uint8_t *iso_file_name size_t iso_file_name_len Ft int Fn mifare_desfire_delete_application MifareTag tag MifareDESFireAID aid Ft int Fn mifare_desfire_get_application_ids MifareTag tag MifareDESFireAID *aids[] size_t *count Ft void Fn mifare_desfire_free_application_ids MifareDESFireAID aids[] Ft int Fn mifare_desfire_get_df_names MifareTag tag MifareDESFireDF *dfs[] size_t *count Ft int Fn mifare_desfire_select_application MifareTag tag MifareDESFireAID aid Ft int Fn mifare_desfire_format_picc MifareTag tag Ft int Fn mifare_desfire_get_version MifareTag tag struct mifare_desfire_version_info *version_info Ft int Fn mifare_desfire_free_mem MifareTag tag uint32_t *size Ft int Fn mifare_desfire_set_configuration MifareTag tag bool disable_format bool enable_random_uid Ft int Fn mifare_desfire_set_default_key MifareTag tag MifareDESFireKey key Ft int Fn mifare_desfire_set_ats MifareTag tag uint8_t *ats Ft int Fn mifare_desfire_get_card_uid MifareTag tag char **uid Ft int Fn mifare_desfire_get_file_ids MifareTag tag uint8_t *files[] size_t *count Ft int Fn mifare_desfire_get_iso_file_ids MifareTag tag uint16_t *files[] size_t *count Ft int Fn mifare_desfire_get_file_settings MifareTag tag uint8_t file_no struct mifare_desfire_file_settings *settings Ft int Fn mifare_desfire_change_file_settings MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights Ft int Fn mifare_desfire_create_std_data_file MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t file_size Ft int Fn mifare_desfire_create_std_data_file_iso MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t file_size uint16_t iso_file_id Ft int Fn mifare_desfire_create_backup_data_file MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t file_size Ft int Fn mifare_desfire_create_backup_data_file_iso MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t file_size uint16_t iso_file_id Ft int Fn mifare_desfire_create_value_file MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights int32_t lower_limit int32_t upper_limit int32_t value uint8_t limited_credit_enable Ft int Fn mifare_desfire_create_linear_record_file MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t record_size uint32_t max_number_of_records Ft int Fn mifare_desfire_create_linear_record_file_iso MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t record_size uint32_t max_number_of_records Ft int Fn mifare_desfire_create_cyclic_record_file MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t record_size uint32_t max_number_of_records uint16_t iso_file_id Ft int Fn mifare_desfire_create_cyclic_record_file_iso MifareTag tag uint8_t file_no uint8_t communication_settings uint16_t access_rights uint32_t record_size uint32_t max_number_of_records uint16_t iso_file_id Ft int Fn mifare_desfire_delete_file MifareTag tag uint8_t file_no Ft ssize_t Fn mifare_desfire_read_data MifareTag tag uint8_t file_no off_t offset size_t length void *data Ft ssize_t Fn mifare_desfire_read_data_ex MifareTag tag uint8_t file_no off_t offset size_t length void *data int cs Ft ssize_t Fn mifare_desfire_write_data MifareTag tag uint8_t file_no off_t offset size_t length void *data Ft ssize_t Fn mifare_desfire_write_data_ex MifareTag tag uint8_t file_no off_t offset size_t length void *data int cs Ft int Fn mifare_desfire_get_value MifareTag tag uint8_t file_no int32_t *value Ft int Fn mifare_desfire_get_value_ex MifareTag tag uint8_t file_no int32_t *value int cs Ft int Fn mifare_desfire_credit MifareTag tag uint8_t file_no int32_t amount Ft int Fn mifare_desfire_credit_ex MifareTag tag uint8_t file_no int32_t amount int cs Ft int Fn mifare_desfire_debit MifareTag tag uint8_t file_no int32_t amount Ft int Fn mifare_desfire_debit_ex MifareTag tag uint8_t file_no int32_t amount int cs Ft int Fn mifare_desfire_limited_credit MifareTag tag uint8_t file_no int32_t amount Ft int Fn mifare_desfire_limited_credit_ex MifareTag tag uint8_t file_no int32_t amount int cs Ft ssize_t Fn mifare_desfire_write_record MifareTag tag uint8_t file_no off_t offset size_t length void *data Ft ssize_t Fn mifare_desfire_write_record_ex MifareTag tag uint8_t file_no off_t offset size_t length void *data int cs Ft ssize_t Fn mifare_desfire_read_records MifareTag tag uint8_t file_no off_t offset size_t length void *data Ft ssize_t Fn mifare_desfire_read_records_ex MifareTag tag uint7_t file_no off_t offset size_t length void *data int cs Ft int Fn mifare_desfire_clear_record_file MifareTag tag uint8_t file_no Ft int Fn mifare_desfire_commit_transaction MifareTag tag Ft int Fn mifare_desfire_abort_transaction MifareTag tag

DESCRIPTION

The Fn mifare_desfire_* functions allows management of Mifare DESFire tags.

Card-level operations

The Fn mifare_desfire_connect and Fn mifare_desfire_disconnect functions activates and deactivates the provided Vt tag . All Fn mifare_desfire_* functions that operates on a Vt tag require it to be on activated.

After activation, the selected application is the master application. It is possible to select another application using the Fn mifare_desfire_select_application function (see bellow).

The Fn mifare_desfire_get_version function retrieve various information about the provided Vt tag , including UID, batch number, production date, and hardware and software information. Refer to the freefare.h header file for details about the Vt version_info field.

The Fn mifare_desfire_free_mem functions returns the Vt size of the free memory on the PICC (in bytes).

The Fn mifare_desfire_set_configuration function can be used to deactivate the format function when setting Vt disable_format to a value different from 0, or swicth the card to use random UDI setting Vt enable_random_uid to a non-zero value.

The Vt mifare_desfire_set_default_key function sets the Vt key argument as the default key for new applications.

The mifare_desfire_set_ats function replace the ATS bytes returned by PICC when it is selected.

The mifare_desfire_get_card_uid function can be used with a PICC configured for using random UID to retrieve the original UID of the target.

The Fn mifare_desfire_format_picc function resets Vt tag to factory defaults. For this function to work, a previous authentication with the card master key is required.

Application-level operations

The Fn mifare_desfire_select_application function makes the application identified by Vt aid the active one. Further file operations will be performed in the context of this application. After a call to Vt mifare_desfire_connect , the default application is the card master application. It can be selected again calling the Fn mifare_desfire_select_application function either with an Vt aid with all its fields set to 0, or by providing the NULL Vt aid .

The Fn mifare_desfire_authenticate function performs an authentication using the key number Vt key_no on the card and the Vt key (3)DES key on Vt tag .

The Fn mifare_desfire_authenticate_aes function performs an authentication using an AES Vt key .

The Fn mifare_desfire_authenticate_iso function performs an ISO authentication using either a 3DES or a 3K3DES Vt key .

The Fn mifare_desfire_get_key_settings function, returns the Vt settings and the number of keys Vt max_keys of the selected application.

The Fn mifare_desfire_change_key_settings function changes the selected application settings to Vt settings . The application number of keys cannot be changed after the application has been created.

The Fn mifare_desfire_change_key changes the key Vt key_no from Vt old_key to Vt new_key on Vt tag . Depending on the application settings, a previous authentication with the same key or another key may be required.

The Fn mifare_desfire_get_key_version function retrieves the Vt version of the key with number Vt key_no of the selected application.

The Fn mifare_desfire_create_application function, creates an application with AID Vt aid , the Vt settings key settings and Vt key_no authentication keys. Authentication keys are set to 0 after creation.

The Fn mifare_desfire_create_application_3k3des and Fn mifare_desfire_create_application_aes functions acts as the Fn mifare_desfire_create_application function except that the whole application is configured to use 3K3DES or AES keys. It is possible to achive the same result using the Fn mifare_desfire_create_application function and ORing the Vt key_no argument with Vt APPLICATION_CRYPTO_3K3DES or Vt APPLICATION_CRYPTO_AES respectively.

The Fn mifare_desfire_create_application_iso acts as the Fn mifare_desfire_create_application function but allows one to specify if the created files within the application shall have an ISO file identifier setting Vt want_iso_file_identifiers to a non-NULL value, a DF can be provided using Vt iso_file_id , as long as an optional file name Vt iso_file_name of length Vt iso_file_name_len (in bytes).

The Fn mifare_desfire_create_application_3k3des_iso and Fn mifare_desfire_create_application_aes_iso function acts as the regular Fn mifare_desfire_create_application_3k3des and Fn mifare_desfire_create_application_aes functions, providing the same extensions ISO parameters of Fn mifare_desfire_create_application_iso .

The Fn mifare_desfire_delete_application deletes the application identified by AID Vt aid .

The Fn mifare_desfire_get_application_ids function returns a list of all applications of the card. The Vt aids array has to be freed after usage calling Fn mifare_desfire_free_application_ids .

The Fn mifare_desfire_get_df_names retrieves the list of DF Vt dfs from Vt tag and set Vt count to the number of idems in the allocated array. Memory has to be freed by the user using free(3).

File-level operations

The Fn mifare_desfire_get_file_ids function returns the list of Vt count files in the selected application as Vt files . The memory allocated for Vt files has to be reclaimed using free(3).

The Fn mifare_desfire_get_iso_file_ids function returns the list of Vt count file ISO identifiers as Vt files . The memory allocated for Vt files has to be reclaimed using free(3).

The Fn mifare_desfire_get_file_settings function retrieves the Vt settings of the file Vt file_no of the selected application of Vt tag .

The Fn mifare_desfire_change_file_settings function change the Vt communication_settings and Vt access_rights of the file Vt file_no of the selected application of Vt tag .

The Fn mifare_desfire_create_* family of functions create a new file Vt file_no with the provided Vt communication_settings and Vt access_rights on Vt tag.

Fn mifare_desfire_create_std_data_file

creates a standard data file of size Vt file_size .

Fn mifare_desfire_create_backup_data_file

creates a backup data file of size Vt file_size .

Fn mifare_desfire_create_value_file

creates a value file of value Vt value constrained in the range Vt lower_limit Vt upper_limit , and with the Vt limited_credit_enable settings.

Fn mifare_desfire_create_linear_record_file

creates a linear record file that can hold Vt max_number_of_records records of size Vt record_size .

Fn mifare_desfire_create_cyclic_record_file

creates a cyclic record file that can hold Vt max_number_of_records records of size Vt record_size .

The Fn mifare_desfire_create_*_iso family of functions acts as the functions without the Vt _iso suffix but provide an additionnal argument Vt iso_file_id .

The Fn mifare_desfire_delete_file removes the file Vt file_no from the selected application of Vt tag .

Data-level operations

The Fn mifare_desfire_read_data function reads Vt length bytes of data from offset Vt offset of the file Vt file_no and copies it to Vt data . If Vt length is set to 0, the file is read to end. The function returns the number of bytes read.

The Fn mifare_desfire_write_data function writes Vt length bytes of data from offset Vt offset of the file Vt file_no and copies it to Vt data . The function returns the number of bytes written.

The Fn mifare_desfire_get_value reads the Vt value of the file Vt file_no of the selected application.

The Fn mifare_desfire_credit function adds Vt amount to the value of the file Vt file_no of the selected application.

The Fn mifare_desfire_debit function substracts Vt amount to the value of the file Vt file_no of the selected application.

to the value of the file Vt file_no of the selected application.

The Fn mifare_desfire_limited_credit function adds Vt amount to the value of the file Vt file_no of the selected application.

The Fn mifare_desfire_write_record function writes Vt length records starting at record Vt offset of Vt data in the file Vt file_no and returns the number of bytes written.

The Fn mifare_desfire_read_records function reads Vt length records starting at record Vt offset from the file Vt file_no and copy them to Vt data , returning the number of bytes read.

The Fn mifare_desfire_clear_record_file function erase all records from the file Vt file_no of the selected application.

The Fn mifare_desfire_commit_transaction validates the set of pending changes on the Vt tag , while the Fn mifare_desfire_abort_transaction rollbacks the changes.

All data-manipulation functions that read data from and write data to files come with an Fn *_ex variant (e.g. Fn mifare_desfire_read_data_ex ) which accepts an extra parameter Vt cs that defines the communication settings to use. If not provided, the library will try to read-out this value from the file's configuration. Because reading this information may be denied, the Fn *_ex variant of functions still allows using the library for advanced usage.

RETURN VALUES

Unless stated otherwise, all other functions return a value greater than or equal to 0 on success or -1 on failure.

AUTHORS

An Romain Tartiere Aq [email protected]