X_Mode

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

Collaboration diagram for X_Mode:

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

Functions
phStatus_t	phhalHw_Sam_Cmd_DESFire_AuthenticatePICC (phhalHw_Sam_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 MIFARE DESFire. More...
phStatus_t	phhalHw_Sam_Cmd_DESFire_ChangeKeyPICC (phhalHw_Sam_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)
	The DESFire_ChangeKeyPICC command supports the procedure to change a key stored in the PICC in X-Mode. More...
phStatus_t	phhalHw_Sam_Cmd_DESFire_WriteX (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wOption, uint8_t bCrypto, uint8_t *pData, uint8_t bDataLen, uint8_t *pPiccReturnCode, uint8_t *pErrLen)
	The DESFire_WriteX command is used to apply the DESFire Secure Messaging in X-mode on PICC commands writing data to the DESFire PICC. More...
phStatus_t	phhalHw_Sam_Cmd_DESFire_ReadX (phhalHw_Sam_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)
	The DESFire_ReadX command is used to remove the DESFire Secure Messaging in X-mode on PICC commands reading data from the DESFire PICC. More...
phStatus_t	phhalHw_Sam_Cmd_DESFire_CreateTMFilePICC (phhalHw_Sam_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 *pTMIExclFileMap, uint8_t bTMKeyOptions, uint8_t bTSIGKeyNo, uint8_t *pDivInput, uint8_t bDivInputLen, uint8_t *pPiccReturnCode)
	The DESFire_CreateTMFilePICC command supports the procedure to create a Transaction MAC File in the PICC in X-mode from a key stored in the SAM. More...

Detailed Description

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

Function Documentation

phhalHw_Sam_Cmd_DESFire_AuthenticatePICC()

phStatus_t phhalHw_Sam_Cmd_DESFire_AuthenticatePICC	(	phhalHw_Sam_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 MIFARE DESFire.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pPCDcap2In, pDivInput, pPDcap2 pPCDcap2 and pPiccReturnCode are NULL.
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 OR. Option for Authentication mode and Authentication type D40 & EV1 authentication type EVx Authenticate first EVx Authenticate non first Option for Suppressing secure messaging Allow secure messaging Suppress secure messaging (for example for originality keys)" Option for Key Derivation Information and Key Diversification Types. AV1 compatibility mode key diversification methods, 3TDEA, AES key AV1 compatibility mode key diversification methods, TDEA Key, diversified using two encryption rounds AV1 compatibility mode key diversification methods, TDEA Key, diversified using one encryption round AV2 mode key diversification methods Option for Key Selection Key selection by key entry number Key selection by DESFire key number Option for Key Diversification No diversification Diversify the used key with the given DivInput
[in]	bISOMode	[In] ISO mode to be used. Command will be sent to PICC using native command set Command will be sent to PICC using ISO/IEC 7816-4APDU ISO compliant authentication (Cmd.ISOGetChallenge, Cmd.ISOExternalAuthenticate and Cmd.ISOInternalAuthenticate) will be performed
[in]	bDFKeyNo	[In] DESFire Key Number to be used for authentication.
[in]	bKeyNo	[In] Key number to be used in SAM or DESFire Key number. If Key selection by DESFire key number, 0x00 - 0x0D should be used. If Key selection by SAM Key Number, then below one should be used NVM Key: 0x00 - 0x7F RAM Key: 0xE0 - 0xE3
[in]	bKeyVer	[In] Key version to be used in SAM.
[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. 0x00 - 0x06: For First Authentication with user defined PCDCaps to use.
[in]	pPCDcap2In	[In] Input PCD capabilities 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 = 0x00 - 0x06: Should not be null. The PCD input capabilities should be passed.
[in]	pDivInput	[In] Diversification Input used to diversify the key. If Diversification is Enabled, then 8 bytes (if AV1 key diversification with DES) 16 bytes (if AV1 key diversification with AES) 1 to 31 bytes (if AV2 key diversification) diversification input NULL otherwise
[in]	bDivInputLen	[In] Length of bytes available in pDivInput buffer.
[out]	pPDcap2	[Out] Buffer containing the output PD capabilities. This will contain 6 bytes of PD information, if targeting EVx authentication type and first authentication.
[out]	pPCDcap2	[Out] Buffer containing the output PCD capabilities. This will contain 6 bytes of PCD information, if targeting EVx authentication type and first authentication.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. Will be 1 byte if bISOMode = Native Format 2 bytes if bISOMode = ISO/IEC 7816-4APDU or ISO compliant authentication format

phhalHw_Sam_Cmd_DESFire_ChangeKeyPICC()

phStatus_t phhalHw_Sam_Cmd_DESFire_ChangeKeyPICC	(	phhalHw_Sam_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
	)

The DESFire_ChangeKeyPICC command supports the procedure to change a key stored in the PICC in X-Mode.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pDivInput and pPiccReturnCode are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bCryptoMethod	[In] Key compilation method. Options for P1 information byte. The options can be combined by bitwise OR. Key diversification method SAM AV1 compatibility diversification method SAM AV2 diversification method SAM AV1 and SAM AV2 Key diversification method Current Key Diversify using two encryption rounds Diversify using one encryption round Do not diversified the current key Diversified the current key New Key Diversify using two encryption rounds Diversify using one encryption round Do not diversified the new key Diversified the new key Cryptogram computation mode PICC targeted key different from the PICC authenticated key PICC targeted key equal to PICC authenticated key. The parameters CurrKeyNo and CurrKeyV are ignored"
[in]	bConfig	[In] Options for P2 information byte. The options can be combined by bitwise OR. ISO mode to be used. Command will be sent to PICC using native command set Command will be sent to PICC using ISO/IEC 7816-4APDU PICC Change Key command Cmd.ChangeKey Cmd.ChangeKeyEV2 PICC master key update Do not include the key type in the cryptogram Include the key type in the cryptogram Number of PICC key to be changed. Will be taken from bDFKeyNo parameter if bConfig has Cmd.ChangeKey
[in]	bKeySetNo	[In] If bConfig = Cmd.ChangeKeyEV2, 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 bConfig = Cmd.ChangeKeyEV2.
[in]	bCurrKeyNo	[In] Number of key entry holding the current key in SAM. NVM Key: 0x00 - 0x7F RAM Key: 0xE0 - 0xE3
[in]	bCurrKeyVer	[In] Key version of the current key in SAM.
[in]	bNewKeyNo	[In] Number of key entry holding the new key in SAM. NVM Key: 0x00 - 0x7F RAM Key: 0xE0 - 0xE3
[in]	bNewKeyVer	[In] Key version of new key in SAM.
[in]	pDivInput	[In] Diversification Input used to diversify the key. If any of diversification option is set in bCryptoMethod parameter, then 8 bytes (if AV1 key diversification with DES) 16 bytes (if AV1 key diversification with AES) 1 to 31 bytes (if AV2 key diversification) diversification input NULL otherwise
[in]	bDivInputLen	[In] Length of bytes available in pDivInput buffer.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. Will be 1 byte if bISOMode = Native Format 2 bytes if bISOMode = ISO/IEC 7816-4APDU.

phhalHw_Sam_Cmd_DESFire_WriteX()

phStatus_t phhalHw_Sam_Cmd_DESFire_WriteX	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCrypto,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t *	pPiccReturnCode,
		uint8_t *	pErrLen
	)

The DESFire_WriteX command is used to apply the DESFire Secure Messaging in X-mode on PICC commands writing data to the DESFire PICC.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pData, pPiccReturnCode and pErrLen are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options for exchanging information to SAM. Exchange information to SAM and Receive the response Buffer first set of information. No exchange is performed Buffer intermediate set of information. No exchange is performed Buffer last set of information. Exchange information to SAM and Receive the response Should be used to exchange chunks of data and receive response. To be ORed with above option and to set LFI flag of P1 byte.
[in]	bCrypto	[In] Option to set the P2 information byte. CAn be combined by using bitwise OR operator. Extended offset Legacy mode (MIFARE SAM AV2) Extended offset Chaining configuration DESFire application chaining (0xAF) ISO/IEC 14443-4 chaining Communication Mode CommMode.Plain CommMode.MAC CommMode.Full Index of byte in data field where crypto operation shall start If Legacy mode: Full Range (0x00 - 0x0F) If Extended offset: RFU (0x00)
[in]	pData	[In] The data to be written to the DESFire PICC. If Extended offset mode, Communication mode is Full and first frame, the buffer should contain offset followed by the PICC related data. For any other options, the buffer should contain only the PICC related data.
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. Will be 1 byte if bISOMode = Native Format 2 bytes if bISOMode = ISO/IEC 7816-4APDU.
[out]	pErrLen	[Out] Length of bytes available in pPiccReturnCode buffer.

phhalHw_Sam_Cmd_DESFire_ReadX()

phStatus_t phhalHw_Sam_Cmd_DESFire_ReadX	(	phhalHw_Sam_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
	)

The DESFire_ReadX command is used to remove the DESFire Secure Messaging in X-mode on PICC commands reading data from the DESFire PICC.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pAppData, pRespLen, pPiccReturnCode and pErrLen are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. Default: To buffer the initial command information. Use this flag to buffer the Length information also in case of FULL communication mode and more data is expected. To receive data in Native Chaining mode To receive data in ISO chaining mode, use Response Chaining | ISO Chaining
[in]	bCrypto	[In] Crypto configuration. Option to set the P2 information byte. CommMode.Plain CommMode.MAC CommMode.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 (0xAF) in case more data is expected.
[in]	bAppDataLen	[In] Length of bytes available in pAppData buffer.
[out]	ppResponse	[Out] The data received from SAM.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.
[out]	pPiccReturnCode	[Out] Error code returned by PICC. Will be 1 byte if pData information exchanged to SAM is in Native format. 2 bytes if pData information exchanged to SAM is in ISO/IEC 7816-4APDU.
[out]	pErrLen	[Out] Length of bytes available in pPiccReturnCode buffer.

phhalHw_Sam_Cmd_DESFire_CreateTMFilePICC()

phStatus_t phhalHw_Sam_Cmd_DESFire_CreateTMFilePICC	(	phhalHw_Sam_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 *	pTMIExclFileMap,
		uint8_t	bTMKeyOptions,
		uint8_t	bTSIGKeyNo,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pPiccReturnCode
	)

The DESFire_CreateTMFilePICC command supports the procedure to create a Transaction MAC File in the PICC in X-mode from a key stored in the SAM.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pAccessRights, pDivInput and pPiccReturnCode are NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Key diversification selection. Options for P1 information byte. No diversification Diversify the used key with the given DivInput
[in]	bISOMode	[In] Options for P2 information byte. Command will be sent to PICC using native command set Command will be sent to PICC using ISO/IEC 7816-4APDU
[in]	bKeyNo	[In] Key number to be used in SAM. One of the following NVM Key: 0x00 - 0x7F RAM Key: 0xE0 - 0xE3
[in]	bKeyVer	[In] Key version to be used in SAM.
[in]	bFileNo	[In] File number of the file to be created.
[in]	bFileOption	[In] Options for the targeted file. Communication Mode FileOptions as PLAIN FileOptions as MAC FileOptions as FULL

• TMI Exclusion file Map. Can bit bitwise OR with above option

  Parameters

  [in]	pAccessRights	[In] Access conditions to be applied for the file. Refer respective product DataSheet for access rights information. This should be two bytes long.
  [in]	pTMIExclFileMap	[In] TMI exclusion FileMap. Should be 4 byte.
  [in]	bTMKeyOptions	[In] Option for the TransactionMAC Key. One of the following, KeyType of the KeyID.AppTransactionMACKey AES128 Key AES256 Key

• Mode. Can bit bitwise OR with above options
  • Transaction MAC
  • Transaction Signature

    Parameters

    [in]	bTSIGKeyNo	[In] Key Number pointing to AppTransactionSIGKey.
    [in]	pDivInput	[In] Diversification Input used to diversify the key.
    [in]	bDivInputLen	[In] Length of bytes available in pDivInput buffer.
    [out]	pPiccReturnCode	[Out] Error code returned by PICC. Will be

  • 1 byte if bISOMode = Native Format
  • 2 bytes if bISOMode = ISO/IEC 7816-4APDU or ISO compliant authentication formats