NXP NFC Reader Library v4.040.05.011646

Modules
MIFARE DESFire (R)
Application Layer

These Functions implement the MIFARE DESFire(R) EV1 commands. More...

Collaboration diagram for MIFARE DESFire (R):

## Modules
| Component : Software

## Other Options for various Functions
#define | PHAL_MFDF_NOT_AUTHENTICATED 0xFFU
| No authentication. More...
#define | PHAL_MFDF_COMMUNICATION_PLAIN 0x00U
| Plain mode of communication. More...
#define | PHAL_MFDF_COMMUNICATION_MACD 0x10U
| MAC mode of communication. More...
#define | PHAL_MFDF_COMMUNICATION_ENC 0x30U
| Enciphered mode of communication. More...
#define | PHAL_MFDF_ADDITIONAL_INFO 0x00A1
| Option for getconfig to get additional info of a generic error. More...

## phalMfdf Custom Error Codes
#define | PHAL_MFDF_NO_CHANGES (PH_ERR_CUSTOM_BEGIN+0)
| MF DF Response - No changes done to backup files. More...
#define | PHAL_MFDF_ERR_OUT_OF_EEPROM_ERROR (PH_ERR_CUSTOM_BEGIN+1)
| MF DF Response - Insufficient NV-Memory. More...
#define | PHAL_MFDF_ERR_NO_SUCH_KEY (PH_ERR_CUSTOM_BEGIN+2)
| MF DF Invalid key number specified. More...
#define | PHAL_MFDF_ERR_PERMISSION_DENIED (PH_ERR_CUSTOM_BEGIN+3)
| MF DF Current configuration/status does not allow the requested command. More...
#define | PHAL_MFDF_ERR_APPLICATION_NOT_FOUND (PH_ERR_CUSTOM_BEGIN+4)
| MF DF Requested AID not found on PICC. More...
#define | PHAL_MFDF_ERR_BOUNDARY_ERROR (PH_ERR_CUSTOM_BEGIN+5)
| MF DF Attempt to read/write data from/to beyond the files/record's limits. More...
#define | PHAL_MFDF_ERR_COMMAND_ABORTED (PH_ERR_CUSTOM_BEGIN+6)
| MF DF Previous cmd not fully completed. More...
#define | PHAL_MFDF_ERR_COUNT (PH_ERR_CUSTOM_BEGIN+7)
| MF DF Num. More...
#define | PHAL_MFDF_ERR_DUPLICATE (PH_ERR_CUSTOM_BEGIN+8)
| MF DF File/Application with same number already exists. More...
#define | PHAL_MFDF_ERR_FILE_NOT_FOUND (PH_ERR_CUSTOM_BEGIN+9)
| MF DF Specified file number does not exist. More...
#define | PHAL_MFDF_ERR_PICC_CRYPTO (PH_ERR_CUSTOM_BEGIN+10)
| MF DF Crypto error returned by PICC. More...
#define | PHAL_MFDF_ERR_PARAMETER_ERROR (PH_ERR_CUSTOM_BEGIN+11)
| MF DF Parameter value error returned by PICC. More...
#define | PHAL_MFDF_ERR_DF_GEN_ERROR (PH_ERR_CUSTOM_BEGIN+12)
| MF DF DesFire Generic error. More...
#define | PHAL_MFDF_ERR_DF_7816_GEN_ERROR (PH_ERR_CUSTOM_BEGIN+13)
| MF DF ISO 7816 Generic error. More...

## PICC level Commands
phStatus_t | phalMfdf_CreateApplication (void *pDataParams, uint8_t bOption, uint8_t *pAid, uint8_t bKeySettings1, uint8_t bKeySettings2, uint8_t *pISOFileId, uint8_t *pISODFName, uint8_t bISODFNameLen)
| Creates new applications on the PICC. More...
phStatus_t | phalMfdf_SelectApplication (void *pDataParams, uint8_t *pAid)
| Selects one particular application on the PICC for further access. More...
phStatus_t | phalMfdf_GetVersion (void *pDataParams, uint8_t *pVerInfo)
| Returns manufacturing related data of the PICC. More...

## Application level Commands
phStatus_t | phalMfdf_CreateStdDataFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bCommSett, uint8_t *pAccessRights, uint8_t *pFileSize)
| Creates files for storage of plain unformatted user data within an existing application on the PICC. More...

## Data Manipulation Commands
phStatus_t | phalMfdf_WriteData (void *pDataParams, uint8_t bCommOption, uint8_t bFileNo, uint8_t *pOffset, uint8_t *pTxData, uint8_t *pTxDataLen)

## ISO 7816 COMMANDS
phStatus_t | phalMfdf_IsoSelectFile (void *pDataParams, uint8_t bOption, uint8_t bSelector, uint8_t *pFid, uint8_t *pDFname, uint8_t bDFnameLen, uint8_t **ppFCI, uint16_t *pwFCILen)
| ISO Select. More...
phStatus_t | phalMfdf_IsoReadBinary (void *pDataParams, uint16_t wOption, uint8_t bOffset, uint8_t bSfid, uint8_t bBytesToRead, uint8_t **ppRxBuffer, uint16_t *pBytesRead)
| ISO Read Binary `wOption` can be one of: . More...
phStatus_t | phalMfdf_IsoUpdateBinary (void *pDataParams, uint8_t bOffset, uint8_t bSfid, uint8_t *pData, uint8_t bDataLen)
| Iso Update Binary. More...

## Miscellaneous functions
phStatus_t | phalMfdf_GetConfig (void *pDataParams, uint16_t wConfig, uint16_t *pValue)
| Perform a GetConfig command. More...
phStatus_t | phalMfdf_SetConfig (void *pDataParams, uint16_t wConfig, uint16_t wValue)
| Perform a SetConfig command. More...

## Detailed Description

These Functions implement the MIFARE DESFire(R) EV1 commands.

## Macro Definition Documentation

## § PHAL_MFDF_NOT_AUTHENTICATED

#define PHAL_MFDF_NOT_AUTHENTICATED 0xFFU

No authentication.

## § PHAL_MFDF_COMMUNICATION_PLAIN

#define PHAL_MFDF_COMMUNICATION_PLAIN 0x00U

Plain mode of communication.

## § PHAL_MFDF_COMMUNICATION_MACD

#define PHAL_MFDF_COMMUNICATION_MACD 0x10U

MAC mode of communication.

## § PHAL_MFDF_COMMUNICATION_ENC

#define PHAL_MFDF_COMMUNICATION_ENC 0x30U

Enciphered mode of communication.

## § PHAL_MFDF_ADDITIONAL_INFO

#define PHAL_MFDF_ADDITIONAL_INFO 0x00A1

Option for getconfig to get additional info of a generic error.

## § PHAL_MFDF_NO_CHANGES

#define PHAL_MFDF_NO_CHANGES (PH_ERR_CUSTOM_BEGIN+0)

MF DF Response - No changes done to backup files.

## § PHAL_MFDF_ERR_OUT_OF_EEPROM_ERROR

#define PHAL_MFDF_ERR_OUT_OF_EEPROM_ERROR (PH_ERR_CUSTOM_BEGIN+1)

MF DF Response - Insufficient NV-Memory.

## § PHAL_MFDF_ERR_NO_SUCH_KEY

#define PHAL_MFDF_ERR_NO_SUCH_KEY (PH_ERR_CUSTOM_BEGIN+2)

MF DF Invalid key number specified.

## § PHAL_MFDF_ERR_PERMISSION_DENIED

#define PHAL_MFDF_ERR_PERMISSION_DENIED (PH_ERR_CUSTOM_BEGIN+3)

MF DF Current configuration/status does not allow the requested command.

## § PHAL_MFDF_ERR_APPLICATION_NOT_FOUND

#define PHAL_MFDF_ERR_APPLICATION_NOT_FOUND (PH_ERR_CUSTOM_BEGIN+4)

MF DF Requested AID not found on PICC.

## § PHAL_MFDF_ERR_BOUNDARY_ERROR

#define PHAL_MFDF_ERR_BOUNDARY_ERROR (PH_ERR_CUSTOM_BEGIN+5)

MF DF Attempt to read/write data from/to beyond the files/record's limits.

## § PHAL_MFDF_ERR_COMMAND_ABORTED

#define PHAL_MFDF_ERR_COMMAND_ABORTED (PH_ERR_CUSTOM_BEGIN+6)

MF DF Previous cmd not fully completed.

Not all frames were requested or provided by the PCD.

## § PHAL_MFDF_ERR_COUNT

#define PHAL_MFDF_ERR_COUNT (PH_ERR_CUSTOM_BEGIN+7)

MF DF Num.

of applns limited to 28. No additional applications possible.

## § PHAL_MFDF_ERR_DUPLICATE

#define PHAL_MFDF_ERR_DUPLICATE (PH_ERR_CUSTOM_BEGIN+8)

MF DF File/Application with same number already exists.

## § PHAL_MFDF_ERR_FILE_NOT_FOUND

#define PHAL_MFDF_ERR_FILE_NOT_FOUND (PH_ERR_CUSTOM_BEGIN+9)

MF DF Specified file number does not exist.

## § PHAL_MFDF_ERR_PICC_CRYPTO

#define PHAL_MFDF_ERR_PICC_CRYPTO (PH_ERR_CUSTOM_BEGIN+10)

MF DF Crypto error returned by PICC.

## § PHAL_MFDF_ERR_PARAMETER_ERROR

#define PHAL_MFDF_ERR_PARAMETER_ERROR (PH_ERR_CUSTOM_BEGIN+11)

MF DF Parameter value error returned by PICC.

## § PHAL_MFDF_ERR_DF_GEN_ERROR

#define PHAL_MFDF_ERR_DF_GEN_ERROR (PH_ERR_CUSTOM_BEGIN+12)

MF DF DesFire Generic error.

Check additional Info.

## § PHAL_MFDF_ERR_DF_7816_GEN_ERROR

#define PHAL_MFDF_ERR_DF_7816_GEN_ERROR (PH_ERR_CUSTOM_BEGIN+13)

MF DF ISO 7816 Generic error.

Check Additional Info.

## Function Documentation

## § phalMfdf_CreateApplication()

phStatus_t phalMfdf_CreateApplication | ( | void * | pDataParams,
|  | uint8_t | bOption,
|  | uint8_t * | pAid,
|  | uint8_t | bKeySettings1,
|  | uint8_t | bKeySettings2,
|  | uint8_t * | pISOFileId,
|  | uint8_t * | pISODFName,
|  | uint8_t | bISODFNameLen
| ) |  |

Creates new applications on the PICC.

bOption value can be

- 01 meaning wISOFileId is supplied
- 02 meaning pISODFName is present
- 03 meaning both wISOFileId and pISODFName are present
- 00 meaning both not present

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure
  [in] | bOption | Option parameter.
  [in] | pAid | array of 3 bytes.
  [in] | bKeySettings1 | 1 byte.
  [in] | bKeySettings2 | 1 byte.
  [in] | pISOFileId | 2 btyes ISO File ID.
  [in] | pISODFName | 1 to 16 Bytes. Can also be NULL.
  [in] | bISODFNameLen | Size of pISODFName if that is present.

## § phalMfdf_SelectApplication()

phStatus_t phalMfdf_SelectApplication | ( | void * | pDataParams,
|  | uint8_t * | pAid
| ) |  |

Selects one particular application on the PICC for further access.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | pAid | 3 byte AID. LSB First.

## § phalMfdf_GetVersion()

phStatus_t phalMfdf_GetVersion | ( | void * | pDataParams,
|  | uint8_t * | pVerInfo
| ) |  |

Returns manufacturing related data of the PICC.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [out] | pVerInfo | 28bytes of version info. User has to parse this.

## § phalMfdf_CreateStdDataFile()

phStatus_t phalMfdf_CreateStdDataFile | ( | void * | pDataParams,
|  | uint8_t | bOption,
|  | uint8_t | bFileNo,
|  | uint8_t * | pISOFileId,
|  | uint8_t | bCommSett,
|  | uint8_t * | pAccessRights,
|  | uint8_t * | pFileSize
| ) |  |

Creates files for storage of plain unformatted user data within an existing application on the PICC.

Remarks
  If bOption==1, it means pIsoFileId is present and is valid. If bOption=0, it means pIsoFileId is not present.
  Communication option (bCommSett) Possible Values are:
  - PHAL_MFDF_COMMUNICATION_PLAIN
  - PHAL_MFDF_COMMUNICATION_ENC
  - PHAL_MFDF_COMMUNICATION_MACD

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | bOption | option parameter. 0x00 means wISOFileId is not provided. 0x01 means wISOFileId is provided and is valid
  [in] | bFileNo | file number.
  [in] | pISOFileId | ISO File ID.
  [in] | bCommSett | communication settings.
  [in] | pAccessRights | 2 byte access rights. Sent LSB first to PICC.
  [in] | pFileSize | 3bytes. Sent LSB first to PICC.

## § phalMfdf_WriteData()

phStatus_t phalMfdf_WriteData | ( | void * | pDataParams,
|  | uint8_t | bCommOption,
|  | uint8_t | bFileNo,
|  | uint8_t * | pOffset,
|  | uint8_t * | pTxData,
|  | uint8_t * | pTxDataLen
| ) |  |

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | bCommOption | Communication Mode. Plain, Mac'd or encrypted.
  [in] | bFileNo | 1 byte file number.
  [in] | pOffset | 3 bytes offset. LSB First.
  [in] | pTxData | Data to be written.
  [in] | pTxDataLen | 3 bytes. length of data to be written.

## § phalMfdf_IsoSelectFile()

phStatus_t phalMfdf_IsoSelectFile | ( | void * | pDataParams,
|  | uint8_t | bOption,
|  | uint8_t | bSelector,
|  | uint8_t * | pFid,
|  | uint8_t * | pDFname,
|  | uint8_t | bDFnameLen,
|  | uint8_t ** | ppFCI,
|  | uint16_t * | pwFCILen
| ) |  |

ISO Select.

Remarks
  bSelector = 0x00 => Selection by 2 byte file Id.
  bSelector = 0x02 => Select EF under current DF. Fid = EF id
  bSelector = 0x04 => Selection by DF Name. DFName and len is then valid

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | bOption | If bOption == 00 FCI is returned. If 0x0C no FCI returned.
  [in] | bSelector | bSelector equals either 0x00 or 0x02 or 0x04.
  [in] | pFid | two byte file id. Send LSB first.
  [in] | pDFname | DFName upto 16 bytes. valid only when bOption = 0x04.
  [in] | bDFnameLen | Length of DFName string provided by the user.
  [out] | ppFCI | File control information.
  [out] | pwFCILen | Length of FCI returned.

## § phalMfdf_IsoReadBinary()

phStatus_t phalMfdf_IsoReadBinary | ( | void * | pDataParams,
|  | uint16_t | wOption,
|  | uint8_t | bOffset,
|  | uint8_t | bSfid,
|  | uint8_t | bBytesToRead,
|  | uint8_t ** | ppRxBuffer,
|  | uint16_t * | pBytesRead
| ) |  |

ISO Read Binary `wOption` can be one of:
.

- PH_EXCHANGE_DEFAULT
- PH_EXCHANGE_RXCHAINING

If status of PH_ERR_SUCCESS_CHAINING is returned Recall this function with wOption PH_EXCHANGE_RXCHAINING to get remaining data.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  PH_ERR_SUCCESS_CHAINING | operation success with chaining.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | wOption | PH_EXCHANGE_DEFAULT or PH_EXCHANGE_RXCHAINING.
  [in] | bOffset | Offset from where to read.
  [in] | bSfid | Short ISO File Id. Bit 7 should be 1 to indicate Sfid is supplied. Else it is treated as MSB of 2Byte offset.
  [in] | bBytesToRead | number of bytes to read. If 0, then entire file to be read.
  [out] | ppRxBuffer | buffer where the read bytes will be stored.
  [out] | pBytesRead | number of bytes read.

## § phalMfdf_IsoUpdateBinary()

phStatus_t phalMfdf_IsoUpdateBinary | ( | void * | pDataParams,
|  | uint8_t | bOffset,
|  | uint8_t | bSfid,
|  | uint8_t * | pData,
|  | uint8_t | bDataLen
| ) |  |

Iso Update Binary.

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlying component.

Parameters

  [in] | pDataParams | Pointer to this layers param structure.
  [in] | bOffset | Offset from where to write.
  [in] | bSfid | Short ISO File Id. Bit 7 should be 1 to indicate Sfid is supplied Else it is treated as MSB of 2Byte offset.
  [in] | pData | data to be written.
  [in] | bDataLen | number of bytes to write.

## § phalMfdf_GetConfig()

phStatus_t phalMfdf_GetConfig | ( | void * | pDataParams,
|  | uint16_t | wConfig,
|  | uint16_t * | pValue
| ) |  |

Perform a GetConfig command.

`wConfig` can be one of:

- PHAL_MFDF_ADDITIONAL_INFO

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlaying component.

Parameters

  [in] | pDataParams | Pointer to this layers parameter structure.
  [in] | wConfig | Item to read.
  [out] | pValue | Read value.

## § phalMfdf_SetConfig()

phStatus_t phalMfdf_SetConfig | ( | void * | pDataParams,
|  | uint16_t | wConfig,
|  | uint16_t | wValue
| ) |  |

Perform a SetConfig command.

`wConfig` can:

- PHAL_MFDF_ADDITIONAL_INFO

Returns
  Status code

Return values

  PH_ERR_SUCCESS | Operation successful.
  Other | Depending on implementation and underlaying component.

Parameters

  [in] | pDataParams | Pointer to this layers parameter structure.
  [in] | wConfig | Item to set.
  [in] | wValue | Value to set.