SAM commands used for MIFARE DESFire communication in X-Mode. More...

Collaboration diagram for X Mode:

Functions
phStatus_t	phhalHw_SamAV3_Cmd_DESFire_AuthenticatePICC (phhalHw_SamAV3_DataParams_t pDataParams, uint8_t bOption, uint8_t bISOMode, uint8_t bDFKeyNo, uint8_t bKeyNo, uint8_t bKeyVer, uint8_t bPCDcap2InLen, uint8_t pPCDcap2In, uint8_t pDivInput, uint8_t bDivInputLen, uint8_t pPDcap2, uint8_t pPCDcap2, uint8_t pPiccReturnCode)
	Perform an authentication procedure between SAM AV3 and DESFire. More...

phStatus_t	phhalHw_SamAV3_Cmd_DESFire_ChangeKeyPICC (phhalHw_SamAV3_DataParams_t pDataParams, uint8_t bCryptoMethod, uint8_t bConfig, uint8_t bKeySetNo, uint8_t bDFKeyNo, uint8_t bCurrKeyNo, uint8_t bCurrKeyVer, uint8_t bNewKeyNo, uint8_t bNewKeyVer, uint8_t pDivInput, uint8_t bDivInputLen, uint8_t *pPiccReturnCode)
	Change a key of a DESFire PICC. More...

phStatus_t	phhalHw_SamAV3_Cmd_DESFire_WriteX (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bCrypto, uint8_t pData, uint8_t bDataLen, uint8_t pPiccReturnCode, uint8_t pErrLen)
	Write data to a DESFire encrypted or MACed. More...

phStatus_t	phhalHw_SamAV3_Cmd_DESFire_ReadX (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bCrypto, uint8_t pAppData, uint8_t bAppDataLen, uint8_t *ppResponse, uint16_t pRespLen, uint8_t pPiccReturnCode, uint8_t pErrLen)
	Read data from a DESFire encrypted or MACed. More...

phStatus_t	phhalHw_SamAV3_Cmd_DESFire_CreateTMFilePICC (phhalHw_SamAV3_DataParams_t pDataParams, uint8_t bOption, uint8_t bISOMode, uint8_t bKeyNo, uint8_t bKeyVer, uint8_t bFileNo, uint8_t bFileOption, uint8_t pAccessRights, uint8_t bTMKeyOptions, uint8_t pDivInput, uint8_t bDivInputLen, uint8_t pPiccReturnCode)
	Performs Create Transaction MAC file. More...

Sam AV3 command code for MIFARE DESFire X features.
#define	PHHAL_HW_SAMAV3_CMD_DESFIRE_AUTHENTICATE_INS 0xDA
	Sam AV3 Instruction code for Cmd.DESFIRE_Authenticate command.

#define	PHHAL_HW_SAMAV3_CMD_DESFIRE_CHANGE_KEY_INS 0xDE
	Sam AV3 Instruction code for Cmd.DESFIRE_ChangeKey command.

#define	PHHAL_HW_SAMAV3_CMD_DESFIRE_WRITE_X_INS 0xD3
	Sam AV3 Instruction code for Cmd.DESFIRE_WriteX command.

#define	PHHAL_HW_SAMAV3_CMD_DESFIRE_READ_X_INS 0xD2
	Sam AV3 Instruction code for Cmd.DESFIRE_ReadX command.

#define	PHHAL_HW_SAMAV3_CMD_DESFIRE_CREATE_TM_FILE_INS 0xD1
	Sam AV3 Instruction code for Cmd.DESFIRE_CreateTMFilePICC command.

Option macros to update the Crypto configuration information for Cmd.DESFire_WriteX and Cmd.DESFire_ReadX commands.
#define	PHHAL_HW_CMD_SAMAV3_NATIVE_CHAINING 0x00
	Sam DESFire chaining as Native.

#define	PHHAL_HW_CMD_SAMAV3_ISO_CHAINING 0x08
	Sam DESFire chaining as ISO.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_PLAIN 0x00
	Sam DESFire communication mode as Plain.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_MAC 0x10
	Sam DESFire communication mode as MAC.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_FULL 0x30
	Sam DESFire communication mode as Full.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_DESFIRE_CHAINING 0x00
	Sam DESFire chaining mode as DESFire application chaining.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_ISO_CHAINING 0x40
	Sam DESFire chaining mode as ISO/IEC 14443-4 chaining.

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_LEGACY_MODE 0x00
	Sam DESFire Extended offset mode as legacy mode (Sam AV2).

#define	PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_EXTENDED_OFFSET 0x80
	Sam DESFire Extended offset mode as EV2 mode.

Detailed Description

SAM commands used for MIFARE DESFire communication in X-Mode.

Function Documentation

◆ phhalHw_SamAV3_Cmd_DESFire_AuthenticatePICC()

phStatus_t phhalHw_SamAV3_Cmd_DESFire_AuthenticatePICC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bISOMode,
		uint8_t	bDFKeyNo,
		uint8_t	bKeyNo,
		uint8_t	bKeyVer,
		uint8_t	bPCDcap2InLen,
		uint8_t *	pPCDcap2In,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pPDcap2,
		uint8_t *	pPCDcap2,
		uint8_t *	pPiccReturnCode
	)

Perform an authentication procedure between SAM AV3 and DESFire.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Option to update the P1 information. The options can be combined by bitwise oring. Option for Authentication mode and Authentication type PHHAL_HW_CMD_SAMAV3_AUTH_MODE_D40_EV1 PHHAL_HW_CMD_SAMAV3_AUTH_MODE_EV2_FIRST_AUTH PHHAL_HW_CMD_SAMAV3_AUTH_MODE_EV2_NON_FIRST_AUTH Option for Supressing secure messaging PHHAL_HW_CMD_SAMAV3_ALLOW_SECURE_MESSAGING PHHAL_HW_CMD_SAMAV3_SUPPRESS_SECURE_MESSAGING Option for Key Derivation Information and Key Diversification Types. PHHAL_HW_CMD_SAMAV3_KDF_AV1 PHHAL_HW_CMD_SAMAV3_KDF_AV1_DOUBLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_AV1_SINGLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_AV2 PHHAL_HW_CMD_SAMAV3_KDF_RFU Option for Key Selection PHHAL_HW_CMD_SAMAV3_KEY_SELECTION_KEY_ENTRY_NUMBER PHHAL_HW_CMD_SAMAV3_KEY_SELECTION_DESFIRE_KEY_NUMBER Option for Key Diversification PHHAL_HW_CMD_SAMAV3_KEY_DIVERSIFICATION_OFF PHHAL_HW_CMD_SAMAV3_KEY_DIVERSIFICATION_ON
[in]	bISOMode	[In] ISO mode to be used. PHHAL_HW_CMD_SAMAV3_ISO_MODE_NATIVE PHHAL_HW_CMD_SAMAV3_ISO_MODE_ISO7816 PHHAL_HW_CMD_SAMAV3_ISO_MODE_ISO_AUTHENTICATION
[in]	bDFKeyNo	[In] DESFire Key Number to be used for authentication.
[in]	bKeyNo	[In] Reference key number to be used in hardware keystore.
[in]	bKeyVer	[In] Reference key version to be used in hardware keystore.
[in]	bPCDcap2InLen	[In] Length of PCDcap2 field in bytes. `0x00` : For NonFirst Authentication. `0x00` : For First Authentication with no input PCDCaps to use. `0xFF` : For First Authentication with default input PCDCaps to use. `0x01` - 0x06: For First Authentication with user defined PCDCaps to use.
[in]	pPCDcap2In	[In] Input PCD capabilites to be exchanged. `NonFirstAuth` : Should be null. `FirstAuth` with no Input PCD capabilities : Should be null. `FirstAuth` with PCDcap2InLen = 0xFF : Should be null. `FirstAuth` with PCDcap2InLen = 0x01 - 0x06: Should not be null. The PCD input capabilities should be passed.
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length of diversification input used to diversify the key.
[out]	pPDcap2	[Out] Buffer containing the output PD capabilities. This will contain 6 bytes of valid PD information.
[out]	pPCDcap2	[Out] Buffer containing the output PCD capabilities. This will contain 6 bytes of valid PCD information.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. This will of 1 byte in length for Native error code and two byte for rest.

◆ phhalHw_SamAV3_Cmd_DESFire_ChangeKeyPICC()

phStatus_t phhalHw_SamAV3_Cmd_DESFire_ChangeKeyPICC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bCryptoMethod,
		uint8_t	bConfig,
		uint8_t	bKeySetNo,
		uint8_t	bDFKeyNo,
		uint8_t	bCurrKeyNo,
		uint8_t	bCurrKeyVer,
		uint8_t	bNewKeyNo,
		uint8_t	bNewKeyVer,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pPiccReturnCode
	)

Change a key of a DESFire PICC.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bCryptoMethod	[In] Options for P1 information byte Key diversification method PHHAL_HW_CMD_SAMAV3_DIV_METHOD_AV1 PHHAL_HW_CMD_SAMAV3_DIV_METHOD_AV2 Sam AV1 and Sam AV2 Key diversification method PHHAL_HW_CMD_SAMAV3_KDF_SAMAV2_RFU PHHAL_HW_CMD_SAMAV3_KDF_CURRENT_KEY_DOUBLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_CURRENT_KEY_SINGLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_NEW_KEY_DOUBLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_NEW_KEY_SINGLE_ENCRYPTION PHHAL_HW_CMD_SAMAV3_KDF_CURRENT_KEY_OFF PHHAL_HW_CMD_SAMAV3_KDF_CURRENT_KEY_ON PHHAL_HW_CMD_SAMAV3_KDF_NEW_KEY_OFF PHHAL_HW_CMD_SAMAV3_KDF_NEW_KEY_ON Cryptogram computation mode PHHAL_HW_CMD_SAMAV3_CRYPTO_MODE_DIFFERENT_KEY PHHAL_HW_CMD_SAMAV3_CRYPTO_MODE_SAME_KEY
[in]	bConfig	[In] Options for P2 information byte. ISO mode to be used. PHHAL_HW_CMD_SAMAV3_ISO_MODE_NATIVE PHHAL_HW_CMD_SAMAV3_ISO_MODE_ISO7816 Command Type PHHAL_HW_CMD_SAMAV3_CMD_TYPE_CHANGE_KEY PHHAL_HW_CMD_SAMAV3_CMD_TYPE_CHANGE_KEY_EV2 PICC master key update PHHAL_HW_CMD_SAMAV3_MASTER_KEY_UPDATE_EXCLUDE_KEYTYPE PHHAL_HW_CMD_SAMAV3_MASTER_KEY_UPDATE_INCLUDE_KEYTYPE Number of DESFire PICC key to be changed. This should be present only if command type is Cmd.ChangeKey.
[in]	bKeySetNo	[In] Key set number to which the key to be changed belongs to.
[in]	bDFKeyNo	[In] Number of DESFire PICC key to be changed. This should be present only if command type is Cmd.ChangeKeyEV2.
[in]	bCurrKeyNo	[In] Reference key number to be used in hardware keystore for CurrentKey.
[in]	bCurrKeyVer	[In] Reference key version to be used in hardware keystore for CurrentKey.
[in]	bNewKeyNo	[In] Reference key number to be used in hardware keystore for NewKey.
[in]	bNewKeyVer	[In] Reference key version to be used in hardware keystore for NewKey.
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length of diversification input used to diversify the key.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. This will of 1 byte in length for Native error code and two byte for rest.

◆ phhalHw_SamAV3_Cmd_DESFire_WriteX()

phStatus_t phhalHw_SamAV3_Cmd_DESFire_WriteX	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCrypto,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t *	pPiccReturnCode,
		uint8_t *	pErrLen
	)

Write data to a DESFire encrypted or MACed.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. To buffer the data locally use the below flags. PH_EXCHANGE_DEFAULT PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST To exchange data in chaining mode use PH_EXCHANGE_TXCHAINING buffering flag.
[in]	bCrypto	[In] Option to set the P2 information byte. Extended offset PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_LEGACY_MODE PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_EXTENDED_OFFSET Chaining configuration. PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_DESFIRE_CHAINING PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_ISO_CHAINING Communication Mode. PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_PLAIN PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_MAC PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_FULL
[in]	pData	[In] The data to be written to the DESFire PICC. If PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_LEGACY_MODE, the buffer should contain only the PICC related data. If PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_EXTENDED_OFFSET, the buffer should contain offset followed by the PICC related data.
[in]	bDataLen	[In] Length of bytes available in Data buffer.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. This will of 1 byte in length for Native error code and two byte for rest.
[out]	pErrLen	[Out] Length of bytes available in PiccReturnCode buffer.

◆ phhalHw_SamAV3_Cmd_DESFire_ReadX()

phStatus_t phhalHw_SamAV3_Cmd_DESFire_ReadX	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCrypto,
		uint8_t *	pAppData,
		uint8_t	bAppDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen,
		uint8_t *	pPiccReturnCode,
		uint8_t *	pErrLen
	)

Read data from a DESFire encrypted or MACed.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. PH_EXCHANGE_DEFAULT: To buffer the initial command information. Use this flag to buffer the Length information also in case of FULL (P2 = 0x30) communication mode and more data is expected. PH_EXCHANGE_RXCHAINING: To receive data in Native chaining mode. PH_EXCHANGE_RXCHAINING \| PHHAL_HW_CMD_SAMAV3_ISO_CHAINING: To receive data in ISO chaining mode.
[in]	bCrypto	[In] Option to set the P2 information byte. Crypto configuration. PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_PLAIN PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_MAC PHHAL_HW_CMD_SAMAV3_CRYPTO_CONFIG_COMM_MODE_FULL
[in]	pAppData	[In] The following information should be passed. `3` bytes length information in case if Communication mode is FULL and more data is expected. `Complete` PICC command header and data to be sent to PICC for initial exchange. `DESFire` Chaining command code in case more data is expected.
[in]	bAppDataLen	[In] Length of bytes available in Data buffer.
[out]	ppResponse	[Out] The data received from Sam hardware.
[out]	pRespLen	[Out] Length of bytes available in Response buffer.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. This will of 1 byte in length for Native error code and two byte for rest.
[out]	pErrLen	[Out] Length of bytes available in PiccReturnCode buffer.

◆ phhalHw_SamAV3_Cmd_DESFire_CreateTMFilePICC()

phStatus_t phhalHw_SamAV3_Cmd_DESFire_CreateTMFilePICC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bISOMode,
		uint8_t	bKeyNo,
		uint8_t	bKeyVer,
		uint8_t	bFileNo,
		uint8_t	bFileOption,
		uint8_t *	pAccessRights,
		uint8_t	bTMKeyOptions,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pPiccReturnCode
	)

Performs Create Transaction MAC file.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Options for P1 information byte. PHHAL_HW_CMD_SAMAV3_KEY_DIVERSIFICATION_OFF PHHAL_HW_CMD_SAMAV3_KEY_DIVERSIFICATION_ON
[in]	bISOMode	[In] Options for P2 information byte. PHHAL_HW_CMD_SAMAV3_ISO_MODE_NATIVE PHHAL_HW_CMD_SAMAV3_ISO_MODE_ISO7816
[in]	bKeyNo	[In] Reference key number to be used in hardware keystore.
[in]	bKeyVer	[In] Reference key version to be used in hardware keystore.
[in]	bFileNo	[In] File number of the file to be created.
[in]	bFileOption	[In] Options for the targeted file. PHHAL_HW_CMD_SAMAV3_CREATE_TM_FILE_COMM_MODE_PLAIN PHHAL_HW_CMD_SAMAV3_CREATE_TM_FILE_COMM_MODE_MAC PHHAL_HW_CMD_SAMAV3_CREATE_TM_FILE_COMM_MODE_FULL
[in]	pAccessRights	[In] Access conditions to be applied for the file. Refer DESFire EV2 datasheet for access rights information. This should be two bytes long.
[in]	bTMKeyOptions	[In] Option for the TransactionMAC Key. PHHAL_HW_CMD_SAMAV3_CREATE_TM_FILE_AES_KEY is currently supported option as per DESFireEV2 datasheet.
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length of diversification input used to diversify the key.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. This will of 1 byte in length for Native error code and two byte for rest.

Functions

Sam AV3 command code for MIFARE DESFire X features.

Option macros to update the Crypto configuration information for Cmd.DESFire_WriteX and Cmd.DESFire_ReadX commands.

Detailed Description

Function Documentation

◆ phhalHw_SamAV3_Cmd_DESFire_AuthenticatePICC()

◆ phhalHw_SamAV3_Cmd_DESFire_ChangeKeyPICC()

◆ phhalHw_SamAV3_Cmd_DESFire_WriteX()

◆ phhalHw_SamAV3_Cmd_DESFire_ReadX()

◆ phhalHw_SamAV3_Cmd_DESFire_CreateTMFilePICC()