MIFARE_DESFIRE(3)

📦 version 0.4.0, in debian bookworm, debian trixie, nixos 26.05, nixpkgs unstable, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 mifare_desfire(3) — Mifare DESFire Manipulation Functions 🌸

okay bestie, sit down, hydrate, because we're about to talk about the Mifare DESFire manipulation functions from libfreefare. this is the good stuff. this is the main character of contactless card libraries. ✨

📛 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

— aka Mifare DESFire Manipulation Functions. that's the whole squad, fr fr. 🫶

📚 LIBRARY

Mifare card manipulation library — that's libfreefare, and you link it with -lfreefare. that's it, that's the vibe. 💅

✨ SYNOPSIS ✨

first thing's first, bestie — you gotta invite the header to the party:

#include <freefare.h>

and now, the whole cast, in order, exactly as they show up:

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);
👀 bestie, real talk, no cap: look at that mifare_desfire_read_records_ex signature. the original page literally says uint7_t file_no. that is not a typo i made up, that's what's written, and uint7_t is not a real type, so write that one down exactly as-is and don't let anyone gaslight you about it. it's giving "someone's typo got enshrined in the docs" and honestly? iconic. 💀

and that's just the cast list, bestie — the lore, the options, and all the juicy behavioral details are coming up in part 2. don't go anywhere. 🌈

✨ DESCRIPTION ✨

okay bestie, so the mifare_desfire_*() functions are literally your whole toolkit for managing Mifare DESFire tags. like, everything. let's go group by group 💅

🎀 Card-level operations 🎀

  • mifare_desfire_connect() and mifare_desfire_disconnect() — these two activate and deactivate the tag you handed over. and lowkey important: every mifare_desfire_*() function that operates on a tag needs that tag to be activated first. no activation, no vibes. 🔥
  • After activation, the application that's selected is the master application. wanna pick a different one? that's mifare_desfire_select_application() (more on that below 👇).
  • mifare_desfire_get_version() — pulls a whole info dump about the tag: UID, batch number, production date, plus hardware and software info. head to the freefare.h header file if you wanna know the deets about the version_info field.
  • mifare_desfire_free_mem() — returns the size of the free memory on the PICC, in bytes. free space check, slay.
  • mifare_desfire_set_configuration() — two uses: you can turn off the format function by setting disable_format to anything that isn't 0, or you can flip the card into using a random UDI by setting enable_random_uid to a non-zero value. ✨
  • mifare_desfire_set_default_key — sets the key argument as the default key for new applications.
  • mifare_desfire_set_ats — replaces the ATS bytes that the PICC returns when it's selected.
  • mifare_desfire_get_card_uid — for a PICC that's configured to use a random UID, this is the one that gets you the original UID of the target. 🕵️
  • mifare_desfire_format_picc() — resets the tag back to factory defaults. ⚠️ for this one to work you need to have authenticated with the card master key beforehand. no key, no reset.

🦋 Application-level operations 🦋

  • mifare_desfire_select_application() — makes the application identified by aid the active one, and every file operation after that happens inside this application's context. after mifare_desfire_connect, the default is the card master application. wanna go back to it? call mifare_desfire_select_application() again, either with an aid that has all its fields set to 0, or by passing NULL as the aid. easy. 💖
  • mifare_desfire_authenticate() — does an authentication using key number key_no on the card and the key (3)DES key on the tag.
  • mifare_desfire_authenticate_aes() — same vibe, but the key is an AES key.
  • mifare_desfire_authenticate_iso() — ISO authentication, using either a 3DES or a 3K3DES key.
  • mifare_desfire_get_key_settings() — hands you the settings plus the number of keys max_keys of the selected application.
  • mifare_desfire_change_key_settings() — changes the selected application's settings to settings. heads up: the application's number of keys cannot be changed once the application has been created. periodt.
  • mifare_desfire_change_key() — changes key key_no from old_key to new_key on the tag. depending on the application's settings, you may need a previous authentication with that same key or with a different one. iykyk.
  • mifare_desfire_get_key_version() — retrieves the version of the key numbered key_no in the selected application.
  • mifare_desfire_create_application() — creates an application with AID aid, the key settings settings, and key_no authentication keys. fun fact: authentication keys get set to 0 after creation.
  • mifare_desfire_create_application_3k3des() and mifare_desfire_create_application_aes() — behave exactly like mifare_desfire_create_application(), except the whole application is configured to use 3K3DES or AES keys respectively. and yes, you can get the same result with plain mifare_desfire_create_application() by ORing the key_no argument with APPLICATION_CRYPTO_3K3DES or APPLICATION_CRYPTO_AES. two paths, one destiny ✨
  • mifare_desfire_create_application_iso() — acts like mifare_desfire_create_application(), but lets you say whether the files created inside the application should have an ISO file identifier, by setting want_iso_file_identifiers to a non-NULL value. you can also provide a DF via iso_file_id, along with an optional file name iso_file_name of length iso_file_name_len (in bytes). 📁
  • mifare_desfire_create_application_3k3des_iso() and mifare_desfire_create_application_aes_iso() — act like the regular mifare_desfire_create_application_3k3des() and mifare_desfire_create_application_aes() functions, with the exact same extra ISO parameters that mifare_desfire_create_application_iso() gives you.
  • mifare_desfire_delete_application() — deletes the application identified by AID aid. bye bestie 👋
  • mifare_desfire_get_application_ids() — returns a list of all applications on the card. 🚨 the aids array has to be freed after you're done, by calling mifare_desfire_free_application_ids(). don't leak, it's not the vibe.
  • mifare_desfire_get_df_names() — retrieves the list of DF dfs from the tag and sets count to the number of items in the allocated array. the memory has to be freed by the user with free(3). yes you, bestie. 💀

🌸 File-level operations 🌸

  • mifare_desfire_get_file_ids() — returns the list of count files in the selected application, as files. the memory allocated for files has to be reclaimed using free(3).
  • mifare_desfire_get_iso_file_ids() — returns the list of count file ISO identifiers, as files. again: memory allocated for files gets reclaimed with free(3).
  • mifare_desfire_get_file_settings() — retrieves the settings of file file_no in the selected application of the tag.
  • mifare_desfire_change_file_settings() — changes the communication_settings and access_rights of file file_no in the selected application of the tag.
  • The mifare_desfire_create_*() family of functions creates a new file file_no with the communication_settings and access_rights you provide, on the tag. the whole squad:
    • 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 with value value, constrained to the range lower_limit to upper_limit, 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, each of size record_size.
    • mifare_desfire_create_cyclic_record_file() — creates a cyclic record file that can hold max_number_of_records records, each of size record_size.
  • The mifare_desfire_create_*_iso() family acts exactly like the versions without the _iso suffix, but they give you one extra argument: iso_file_id. 🎁
  • mifare_desfire_delete_file() — removes file file_no from the selected application of the tag. gone, not sorry.

💜 Data-level operations 💜

  • mifare_desfire_read_data() — reads length bytes of data starting at offset from file file_no and copies it into data. if length is set to 0, the file gets read all the way to the end. it returns the number of bytes read. 📖
  • mifare_desfire_write_data() — writes length bytes of data from offset into file file_no, taking it from data. returns the number of bytes written. ✍️
  • mifare_desfire_get_value() — reads the value of file file_no in the selected application.
  • mifare_desfire_credit() — adds amount to the value of file file_no in the selected application.
  • mifare_desfire_debit() — subtracts amount from the value of file file_no in the selected application.
ngl there's a lil orphan fragment sitting right here in the original that just reads: to the value of the file file_no of the selected application. — i'm keeping it, word for word, so nothing goes missing. mystery line, iconic behaviour 💀
  • mifare_desfire_limited_credit() — adds amount to the value of file file_no in the selected application.
  • mifare_desfire_write_record() — writes length records starting at record offset of data into file file_no, and returns the number of bytes written.
  • mifare_desfire_read_records() — reads length records starting at record offset from file file_no and copies them into data, returning the number of bytes read.
  • mifare_desfire_clear_record_file() — erases all records from file file_no in the selected application. wipe the slate clean ✨
  • mifare_desfire_commit_transaction() — validates the set of pending changes on the tag, while mifare_desfire_abort_transaction() rolls them back. one says yes, the other says sike.

and okay, super important bit for the advanced girlies: every data-manipulation function that reads from or writes to files has an *_ex() variant (for example mifare_desfire_read_data_ex()), and that variant takes an extra parameter cs which defines the communication settings to use. if you don't pass it, the library tries to read this value out of the file's configuration. and because reading that information might be denied, the *_ex() variant of functions still lets you use the library for advanced usage. so when the normal path gets blocked, the _ex path is your main character moment. 👑

🔥 RETURN VALUES 🔥

Unless it says otherwise somewhere, every other function returns a value greater than or equal to 0 on success, or -1 on failure.

👀 SEE ALSO 👀

freefare(3)

👑 AUTHORS 👑

Romain Tartiere <romain@il4p.org>

aaaand that's the whole page bestie, we ate and left no crumbs 🫶 this lil beauty shipped as part of the Debian project, dated March 26, 2011, and it lives under the name MIFARE_DESFIRE(3). go forth and desfire responsibly 💖🎀🦋

📦 where this page comes from