NXP Reader Library  v17.1.0.2535
Commands_FileManagement

These Components implement the MIFARE DESFire EVx File Management related commands. More...

Collaboration diagram for Commands_FileManagement:

Functions

phStatus_t phalMfdfEVx_CreateStdDataFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pFileSize)
 Creates files for the storage of plain unformatted user data within an existing application on the PICC. More...
 
phStatus_t phalMfdfEVx_CreateBackupDataFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t *pFileSize)
 Creates files for the storage of plain unformatted user data within an existing application on the PICC, additionally supporting the feature of an integrated backup mechanism. More...
 
phStatus_t phalMfdfEVx_CreateValueFile (void *pDataParams, uint8_t bFileNo, uint8_t bCommSett, uint8_t *pAccessRights, uint8_t *pLowerLmit, uint8_t *pUpperLmit, uint8_t *pValue, uint8_t bLimitedCredit)
 Creates files for the storage and manipulation of 32bit signed integer values within an existing application on the PICC. More...
 
phStatus_t phalMfdfEVx_CreateLinearRecordFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bCommSett, uint8_t *pAccessRights, uint8_t *pRecordSize, uint8_t *pMaxNoOfRec)
 Creates files for multiple storage of structural similar data, for example for loyalty programs within an existing application. More...
 
phStatus_t phalMfdfEVx_CreateCyclicRecordFile (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pISOFileId, uint8_t bCommSett, uint8_t *pAccessRights, uint8_t *pRecordSize, uint8_t *pMaxNoOfRec)
 Creates files for multiple storage of structural similar data, for example for logging transactions, within an existing application. More...
 
phStatus_t phalMfdfEVx_CreateTransactionMacFile (void *pDataParams, uint16_t wOption, uint8_t bFileNo, uint8_t bCommSett, uint8_t *pAccessRights, uint16_t wKeyNo, uint8_t bKeyType, uint8_t *bTMKey, uint8_t bTMKeyVer, uint8_t *pDivInput, uint8_t bDivInputLength)
 Creates a Transaction MAC File and enables the Transaction MAC feature for the targeted application. More...
 
phStatus_t phalMfdfEVx_DeleteFile (void *pDataParams, uint8_t bFileNo)
 Permanently deactivates a file within the file directory of the currently selected application. More...
 
phStatus_t phalMfdfEVx_GetFileIDs (void *pDataParams, uint8_t *pFid, uint8_t *bNumFid)
 Returns the file IDs of all active files within the currently selected application. More...
 
phStatus_t phalMfdfEVx_GetISOFileIDs (void *pDataParams, uint8_t *pFidBuffer, uint8_t *bNumFid)
 Get the ISO File IDs. More...
 
phStatus_t phalMfdfEVx_GetFileSettings (void *pDataParams, uint8_t bFileNo, uint8_t *pFSBuffer, uint8_t *bBufferLen)
 Get information on the properties of a specific file. More...
 
phStatus_t phalMfdfEVx_GetFileCounters (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t *pFileCounters, uint8_t *pRxLen)
 Get file related counters used for Secure Dynamic Messaging. More...
 
phStatus_t phalMfdfEVx_ChangeFileSettings (void *pDataParams, uint8_t bOption, uint8_t bFileNo, uint8_t bFileOption, uint8_t *pAccessRights, uint8_t bAddInfoLen, uint8_t *pAddInfo)
 Changes the access parameters of an existing file. More...
 

The File Option to be used.

#define PHAL_MFDFEVX_FILE_OPTION_PLAIN   0x00U
 Plain mode of communication.
 
#define PHAL_MFDFEVX_FILE_OPTION_PLAIN_1   0x02U
 Plain mode of communication.
 
#define PHAL_MFDFEVX_FILE_OPTION_MACD   0x01U
 MAC mode of communication.
 
#define PHAL_MFDFEVX_FILE_OPTION_ENC   0x03U
 Enciphered mode of communication.
 
#define PHAL_MFDFEVX_FILE_OPTION_MFC_MAPPING_ENABLED   0x20U
 MIFARE Classic mapping support enabled.
 
#define PHAL_MFDFEVX_FILE_OPTION_SDM_MIRRORING_ENABLED   0x40U
 Secure Dynamic Messaging and Mirroring support enabled.
 
#define PHAL_MFDFEVX_FILE_OPTION_ADDITIONAL_AR_PRESENT   0x80U
 Additional Access Rights enabled.
 

Option for CreateValueFile file command.

#define PHAL_MFDFEVX_ENABLE_LIMITEDCREDIT   0x01U
 Bit 0 set to 1 to enable Limited credit.
 
#define PHAL_MFDFEVX_ENABLE_FREE_GETVALUE   0x02U
 Bit 1 set to 1 to enable free GetValue.
 

Options to diversify the key.

#define PHAL_MFDFEVX_CREATE_TMAC_FILE_DIV_OFF   0x00
 Option to disable key diversification.
 
#define PHAL_MFDFEVX_CREATE_TMAC_FILE_DIV_ON   0x01
 Option to enable key diversification.
 
#define PHAL_MFDFEVX_DIVERSIFICATION_OFF   0xFFFFU
 Option to disable key diversification.
 
#define PHAL_MFDFEVX_DIVERSIFICATION_ON   0x0000U
 Option to enable key diversification.
 

The File option and other flags for ChangeFileSettings command.

#define PHAL_MFDFEVX_EXCHANGE_ADD_INFO_BUFFER_COMPLETE   0x80
 To exchange the information available in pAddInfo buffer as is.
 
#define PHAL_MFDFEVX_FILE_OPTION_TMCLIMIT_PRESENT   0x20
 5th Bit of FileOption indicating TMC limit config.
 

Detailed Description

These Components implement the MIFARE DESFire EVx File Management related commands.

Function Documentation

◆ phalMfdfEVx_CreateStdDataFile()

phStatus_t phalMfdfEVx_CreateStdDataFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pFileSize 
)

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

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the present of ISO information.
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]pISOFileId[In] ISO File ID to be used. Will be two bytes.
[in]bFileOption[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pFileSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created then the FileSize will be 10 00 00.

◆ phalMfdfEVx_CreateBackupDataFile()

phStatus_t phalMfdfEVx_CreateBackupDataFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t pFileSize 
)

Creates files for the storage of plain unformatted user data within an existing application on the PICC, additionally supporting the feature of an integrated backup mechanism.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the present of ISO information.
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]pISOFileId[In] ISO File ID to be used. Will be two bytes.
[in]bFileOption[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pFileSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created then the FileSize will be 10 00 00.

◆ phalMfdfEVx_CreateValueFile()

phStatus_t phalMfdfEVx_CreateValueFile ( void *  pDataParams,
uint8_t  bFileNo,
uint8_t  bCommSett,
uint8_t pAccessRights,
uint8_t pLowerLmit,
uint8_t pUpperLmit,
uint8_t pValue,
uint8_t  bLimitedCredit 
)

Creates files for the storage and manipulation of 32bit signed integer values within an existing application on the PICC.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]bCommSett[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pLowerLmit[In] The lower limit for the file. Will be of 4 bytes with LSB first. If size 0x10 need to be created then the value will be 10 00 00 00.
[in]pUpperLmit[In] The upper limit for the file. Will be of 4 bytes with LSB first. If size 0x20 need to be created then the value will be 20 00 00 00.
[in]pValue[In] The initial value. Will be of 4 bytes with LSB first. If size 0x10 need to be created then the value will be 10 00 00 00.
[in]bLimitedCredit[In] One of the below values.

◆ phalMfdfEVx_CreateLinearRecordFile()

phStatus_t phalMfdfEVx_CreateLinearRecordFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bCommSett,
uint8_t pAccessRights,
uint8_t pRecordSize,
uint8_t pMaxNoOfRec 
)

Creates files for multiple storage of structural similar data, for example for loyalty programs within an existing application.

Once the file is filled, further writing is not possible unless it is cleared.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the present of ISO information.
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]pISOFileId[In] ISO File ID to be used. Will be two bytes.
[in]bCommSett[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pRecordSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created then the RecordSize will be 10 00 00.
[in]pMaxNoOfRec[In] The maximum number of record in the file. Will be of 3 bytes with LSB first. If size 0x04 need to be created then the value will be 04 00 00.

◆ phalMfdfEVx_CreateCyclicRecordFile()

phStatus_t phalMfdfEVx_CreateCyclicRecordFile ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pISOFileId,
uint8_t  bCommSett,
uint8_t pAccessRights,
uint8_t pRecordSize,
uint8_t pMaxNoOfRec 
)

Creates files for multiple storage of structural similar data, for example for logging transactions, within an existing application.

Once the file is filled, the PICC automatically overwrites the oldest record with the latest written one.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Option to represent the present of ISO information.
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]pISOFileId[In] ISO File ID to be used. Will be two bytes.
[in]bCommSett[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]pRecordSize[In] The size of the file. Will be of 3 bytes with LSB first. If size 0x10 need to be created then the RecordSize will be 10 00 00.
[in]pMaxNoOfRec[In] The maximum number of record in the file. Will be of 3 bytes with LSB first. If size 0x04 need to be created then the value will be 04 00 00.

◆ phalMfdfEVx_CreateTransactionMacFile()

phStatus_t phalMfdfEVx_CreateTransactionMacFile ( void *  pDataParams,
uint16_t  wOption,
uint8_t  bFileNo,
uint8_t  bCommSett,
uint8_t pAccessRights,
uint16_t  wKeyNo,
uint8_t  bKeyType,
uint8_t bTMKey,
uint8_t  bTMKeyVer,
uint8_t pDivInput,
uint8_t  bDivInputLength 
)

Creates a Transaction MAC File and enables the Transaction MAC feature for the targeted application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]wOption[In] One of the below options. Only applicable for SAM S / X component
[in]bFileNo[In] The file number to be created. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]bCommSett[In] Communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]wKeyNo[In] Key number in SAM KeyStore. For software is not applicable.
[in]bKeyType[In] The TMKeyOption and should be always PHAL_MFDFEVX_KEY_TYPE_AES128.
[in]bTMKey[In] The 16 byte key value to be stored in the PICC. This is applicable for Software only.
[in]bTMKeyVer[In] The version for the key to be stored in the PICC. This is applicable for Software and SAM.
[in]pDivInput[In] Diversification input. Can be NULL.
[in]bDivInputLength[In] Length of diversification input max 31B.

◆ phalMfdfEVx_DeleteFile()

phStatus_t phalMfdfEVx_DeleteFile ( void *  pDataParams,
uint8_t  bFileNo 
)

Permanently deactivates a file within the file directory of the currently selected application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number to be deleted. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.

◆ phalMfdfEVx_GetFileIDs()

phStatus_t phalMfdfEVx_GetFileIDs ( void *  pDataParams,
uint8_t pFid,
uint8_t bNumFid 
)

Returns the file IDs of all active files within the currently selected application.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[out]pFid[Out] The buffer containing the available file ID(s). Buffer should be 32 bytes.
[out]bNumFid[Out] The length of bytes available in FID buffer.

◆ phalMfdfEVx_GetISOFileIDs()

phStatus_t phalMfdfEVx_GetISOFileIDs ( void *  pDataParams,
uint8_t pFidBuffer,
uint8_t bNumFid 
)

Get the ISO File IDs.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[out]pFidBuffer[Out] The buffer containing the available ISO file ID(s). Buffer should be 64 bytes.
[out]bNumFid[Out] The number of ISO File ID's read.

◆ phalMfdfEVx_GetFileSettings()

phStatus_t phalMfdfEVx_GetFileSettings ( void *  pDataParams,
uint8_t  bFileNo,
uint8_t pFSBuffer,
uint8_t bBufferLen 
)

Get information on the properties of a specific file.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bFileNo[In] The file number for which the setting to be retrieved. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[out]pFSBuffer[Out] The buffer containing the settings.
[out]bBufferLen[Out] The length of bytes available in FSBuffer buffer.

◆ phalMfdfEVx_GetFileCounters()

phStatus_t phalMfdfEVx_GetFileCounters ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t pFileCounters,
uint8_t pRxLen 
)

Get file related counters used for Secure Dynamic Messaging.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Indicates the mode of communication to be used while exchanging the data to PICC.
[in]bFileNo[In] File number for which the Counter information need to be received.
[out]pFileCounters[Out] The SDMReadCounter information returned by the PICC.
[out]pRxLen[Out] Length of bytes available in FileCounters buffer.

◆ phalMfdfEVx_ChangeFileSettings()

phStatus_t phalMfdfEVx_ChangeFileSettings ( void *  pDataParams,
uint8_t  bOption,
uint8_t  bFileNo,
uint8_t  bFileOption,
uint8_t pAccessRights,
uint8_t  bAddInfoLen,
uint8_t pAddInfo 
)

Changes the access parameters of an existing file.

Returns
Status code
Return values
PH_ERR_SUCCESSOperation successful.
OtherDepending on implementation and underlying component.
Parameters
[in]pDataParams[In] Pointer to this layer's parameter structure.
[in]bOption[In] Indicates the mode of communication to be used while exchanging the data to PICC.
[in]bFileNo[In] File number for which the setting need to be updated. ORed with PHAL_MFDFEVX_SAI to indicate secondary application indicator.
[in]bFileOption[In] New communication settings for the file.
[in]pAccessRights[In] The new access right to be applied for the file. Should be 2 byte.
[in]bAddInfoLen[In] Complete length consisting of
[in]pAddInfo[In] Buffer should contain the following information.
[Additional access rights] || [SDMOption || SDM AccessRights || VCUIDOffset || SDMReadCtrOffset || PICCDataOffset || SDMACInputOffset || SDMENCOffset || SDMENCLength || SDMMACOffset] || [TMCLimit]