---
name: "mifare_desfire"
section: "3"
platform: "linux"
package: "libfreefare-doc"
version: "0.4.0-2.3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/mifare_desfire"
---

# mifare\_desfire(3)

Mifare DESFire Manipulation Functions

## 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)](/free/3.md).

### 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)](/free/3.md).

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)](/free/3.md).

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)](/freefare/3.md)

## AUTHORS

Romain Tartiere ⟨romain@il4p.org⟩