Provided by: libfreefare-doc_0.4.0-2.3build2_all bug

NAME

     mifare_desfire_connect, mifare_desfire_disconnect.  mifare_desfire_authenticate,
     mifare_desfire_authenticate_aes, mifare_desfire_authenticate_iso,
     mifare_desfire_change_key_settings, mifare_desfire_get_key_settings,
     mifare_desfire_change_key, mifare_desfire_get_key_version,
     mifare_desfire_create_application, mifare_desfire_create_application_3k3des,
     mifare_desfire_create_application_aes, mifare_desfire_create_application_iso,
     mifare_desfire_create_application_3k3des_iso, mifare_desfire_create_application_aes_iso,
     mifare_desfire_delete_application, mifare_desfire_get_application_ids,
     mifare_desfire_free_application_ids, mifare_desfire_get_df_names,
     mifare_desfire_select_application, mifare_desfire_format_picc, mifare_desfire_get_version,
     mifare_desfire_free_mem, mifare_desfire_set_configuration, mifare_desfire_set_default_key,
     mifare_desfire_set_ats, mifare_desfire_get_card_uid, mifare_desfire_get_file_ids,
     mifare_desfire_get_iso_file_ids, mifare_desfire_get_file_settings,
     mifare_desfire_change_file_settings, mifare_desfire_create_std_data_file,
     mifare_desfire_create_std_data_file_iso, mifare_desfire_create_backup_data_file,
     mifare_desfire_create_backup_data_file_iso, mifare_desfire_create_value_file,
     mifare_desfire_create_linear_record_file, mifare_desfire_create_linear_record_file_iso,
     mifare_desfire_create_cyclic_record_file, mifare_desfire_create_cyclic_record_file_iso,
     mifare_desfire_delete_file, mifare_desfire_read_data, mifare_desfire_read_data_ex,
     mifare_desfire_write_data, mifare_desfire_write_data_ex, mifare_desfire_get_value,
     mifare_desfire_get_value_ex, mifare_desfire_credit, mifare_desfire_credit_ex,
     mifare_desfire_debit, mifare_desfire_debit_ex, mifare_desfire_limited_credit,
     mifare_desfire_limited_credit_ex, mifare_desfire_write_record,
     mifare_desfire_write_record_ex, mifare_desfire_read_records, mifare_desfire_read_records_ex,
     mifare_desfire_clear_record_file, mifare_desfire_commit_transaction,
     mifare_desfire_abort_transaction, — Mifare DESFire Manipulation Functions

LIBRARY

     Mifare card manipulation library (libfreefare, -lfreefare)

SYNOPSIS

     #include <freefare.h>

     int
     mifare_desfire_connect(MifareTag tag);

     int
     mifare_desfire_disconnect(MifareTag tag);

     int
     mifare_desfire_authenticate(MifareTag tag, uint8_t key_no, MifareDESFireKey key);

     int
     mifare_desfire_authenticate_aes(MifareTag tag, uint8_t key_no, MifareDESFireKey key);

     int
     mifare_desfire_authenticate_iso(MifareTag tag, uint8_t key_no, MifareDESFireKey key);

     int
     mifare_desfire_change_key_settings(MifareTag tag, uint8_t settings);

     int
     mifare_desfire_get_key_settings(MifareTag tag, uint8_t *settings, uint8_t *max_keys);

     int
     mifare_desfire_change_key(MifareTag tag, uint8_t key_no, MifareDESFireKey new_key,
         MifareDESFireKey old_key);

     int
     mifare_desfire_get_key_version(MifareTag tag, uint8_t key_no, uint8_t *version);

     int
     mifare_desfire_create_application(MifareTag tag, MifareDESFireAID aid, uint8_t settings,
         uint8_t key_no);

     int
     mifare_desfire_create_application_aes(MifareTag tag, MifareDESFireAID aid, uint8_t settings,
         uint8_t key_no);

     int
     mifare_desfire_create_application_3k3des(MifareTag tag, MifareDESFireAID aid,
         uint8_t settings, uint8_t key_no);

     int
     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);

     int
     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);

     int
     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);

     int
     mifare_desfire_delete_application(MifareTag tag, MifareDESFireAID aid);

     int
     mifare_desfire_get_application_ids(MifareTag tag, MifareDESFireAID *aids[], size_t *count);

     void
     mifare_desfire_free_application_ids(MifareDESFireAID aids[]);

     int
     mifare_desfire_get_df_names(MifareTag tag, MifareDESFireDF *dfs[], size_t *count);

     int
     mifare_desfire_select_application(MifareTag tag, MifareDESFireAID aid);

     int
     mifare_desfire_format_picc(MifareTag tag);

     int
     mifare_desfire_get_version(MifareTag tag, struct mifare_desfire_version_info *version_info);

     int
     mifare_desfire_free_mem(MifareTag tag, uint32_t *size);

     int
     mifare_desfire_set_configuration(MifareTag tag, bool disable_format,
         bool enable_random_uid);

     int
     mifare_desfire_set_default_key(MifareTag tag, MifareDESFireKey key);

     int
     mifare_desfire_set_ats(MifareTag tag, uint8_t *ats);

     int
     mifare_desfire_get_card_uid(MifareTag tag, char **uid);

     int
     mifare_desfire_get_file_ids(MifareTag tag, uint8_t *files[], size_t *count);

     int
     mifare_desfire_get_iso_file_ids(MifareTag tag, uint16_t *files[], size_t *count);

     int
     mifare_desfire_get_file_settings(MifareTag tag, uint8_t file_no,
         struct mifare_desfire_file_settings *settings);

     int
     mifare_desfire_change_file_settings(MifareTag tag, uint8_t file_no,
         uint8_t communication_settings, uint16_t access_rights);

     int
     mifare_desfire_create_std_data_file(MifareTag tag, uint8_t file_no,
         uint8_t communication_settings, uint16_t access_rights, uint32_t file_size);

     int
     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);

     int
     mifare_desfire_create_backup_data_file(MifareTag tag, uint8_t file_no,
         uint8_t communication_settings, uint16_t access_rights, uint32_t file_size);

     int
     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);

     int
     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);

     int
     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);

     int
     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);

     int
     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);

     int
     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);

     int
     mifare_desfire_delete_file(MifareTag tag, uint8_t file_no);

     ssize_t
     mifare_desfire_read_data(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data);

     ssize_t
     mifare_desfire_read_data_ex(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data, int cs);

     ssize_t
     mifare_desfire_write_data(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data);

     ssize_t
     mifare_desfire_write_data_ex(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data, int cs);

     int
     mifare_desfire_get_value(MifareTag tag, uint8_t file_no, int32_t *value);

     int
     mifare_desfire_get_value_ex(MifareTag tag, uint8_t file_no, int32_t *value, int cs);

     int
     mifare_desfire_credit(MifareTag tag, uint8_t file_no, int32_t amount);

     int
     mifare_desfire_credit_ex(MifareTag tag, uint8_t file_no, int32_t amount, int cs);

     int
     mifare_desfire_debit(MifareTag tag, uint8_t file_no, int32_t amount);

     int
     mifare_desfire_debit_ex(MifareTag tag, uint8_t file_no, int32_t amount, int cs);

     int
     mifare_desfire_limited_credit(MifareTag tag, uint8_t file_no, int32_t amount);

     int
     mifare_desfire_limited_credit_ex(MifareTag tag, uint8_t file_no, int32_t amount, int cs);

     ssize_t
     mifare_desfire_write_record(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data);

     ssize_t
     mifare_desfire_write_record_ex(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data, int cs);

     ssize_t
     mifare_desfire_read_records(MifareTag tag, uint8_t file_no, off_t offset, size_t length,
         void *data);

     ssize_t
     mifare_desfire_read_records_ex(MifareTag tag, uint7_t file_no, off_t offset, size_t length,
         void *data, int cs);

     int
     mifare_desfire_clear_record_file(MifareTag tag, uint8_t file_no);

     int
     mifare_desfire_commit_transaction(MifareTag tag);

     int
     mifare_desfire_abort_transaction(MifareTag tag);

DESCRIPTION

     The mifare_desfire_*() functions allows management of Mifare DESFire tags.

   Card-level operations
     The mifare_desfire_connect() and mifare_desfire_disconnect() functions activates and
     deactivates the provided tag.  All mifare_desfire_*() functions that operates on a 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 mifare_desfire_select_application() function (see
     bellow).

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

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

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

     The mifare_desfire_set_default_key function sets the 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 mifare_desfire_format_picc() function resets tag to factory defaults.  For this function
     to work, a previous authentication with the card master key is required.

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

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

     The mifare_desfire_authenticate_aes() function performs an authentication using an AES key.

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

     The mifare_desfire_get_key_settings() function, returns the settings and the number of keys
     max_keys of the selected application.

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

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

     The mifare_desfire_get_key_version() function retrieves the version of the key with number
     key_no of the selected application.

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

     The mifare_desfire_create_application_3k3des() and mifare_desfire_create_application_aes()
     functions acts as the 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 mifare_desfire_create_application() function and ORing the key_no argument
     with APPLICATION_CRYPTO_3K3DES or APPLICATION_CRYPTO_AES respectively.

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

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

     The mifare_desfire_delete_application() deletes the application identified by AID aid.

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

     The mifare_desfire_get_df_names() retrieves the list of DF dfs from tag and set 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 mifare_desfire_get_file_ids() function returns the list of count files in the selected
     application as files.  The memory allocated for files has to be reclaimed using free(3).

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

     The mifare_desfire_get_file_settings() function retrieves the settings of the file file_no
     of the selected application of tag.

     The mifare_desfire_change_file_settings() function change the communication_settings and
     access_rights of the file file_no of the selected application of tag.

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

     mifare_desfire_create_std_data_file()
             creates a standard data file of size file_size.

     mifare_desfire_create_backup_data_file()
             creates a backup data file of size file_size.

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

     mifare_desfire_create_linear_record_file()
             creates a linear record file that can hold max_number_of_records records of size
             record_size.

     mifare_desfire_create_cyclic_record_file()
             creates a cyclic record file that can hold max_number_of_records records of size
             record_size.

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

     The mifare_desfire_delete_file() removes the file file_no from the selected application of
     tag.

   Data-level operations
     The mifare_desfire_read_data() function reads length bytes of data from offset offset of the
     file file_no and copies it to data.  If length is set to 0, the file is read to end. The
     function returns the number of bytes read.

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

     The mifare_desfire_get_value() reads the value of the file file_no of the selected
     application.

     The mifare_desfire_credit() function adds amount to the value of the file file_no of the
     selected application.

     The mifare_desfire_debit() function substracts amount to the value of the file file_no of
     the selected application.

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

     The mifare_desfire_limited_credit() function adds amount to the value of the file file_no of
     the selected application.

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

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

     The mifare_desfire_clear_record_file() function erase all records from the file file_no of
     the selected application.

     The mifare_desfire_commit_transaction() validates the set of pending changes on the tag,
     while the mifare_desfire_abort_transaction() rollbacks the changes.

     All data-manipulation functions that read data from and write data to files come with an
     *_ex() variant (e.g.  mifare_desfire_read_data_ex()) which accepts an extra parameter 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 *_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.

SEE ALSO

     freefare(3)

AUTHORS

     Romain Tartiere <romain@il4p.org>