S Mode

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

Collaboration diagram for S Mode:

Functions
phStatus_t	phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part1 (phhalHw_SamAV3_DataParams_t *pDataParams, uint8_t bOption, uint8_t bKeyNo, uint8_t bKeyVer, uint8_t bAuthMode, uint8_t *pDivInput, uint8_t bDivInputLen, uint8_t *pCardResponse, uint8_t bCardRespLen, uint8_t **ppSamResponse, uint16_t *pSamRespLen)
	Performs first part of encryption and decryption of data received from Card and to be sent to Card. More...
phStatus_t	phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part2 (phhalHw_SamAV3_DataParams_t *pDataParams, uint8_t bPiccErrorCode, uint8_t *pCardResponse, uint8_t bCardRespLen, uint8_t *pPDcap2, uint8_t *pPCDcap2, uint8_t *pStatusCode)
	Performs second part of decryption of data received from Card. More...
phStatus_t	phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part1 (phhalHw_SamAV3_DataParams_t *pDataParams, uint8_t bOption, uint8_t bKeyNo, uint8_t bKeyVer, uint8_t *pDivInput, uint8_t bDivInputLen, uint8_t *pCardResponse, uint8_t bCardRespLen, uint8_t **ppSamResponse, uint16_t *pSamRespLen)
	Performs first part of encryption and decryption of data received from Card and to be sent to Card. More...
phStatus_t	phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part2 (phhalHw_SamAV3_DataParams_t *pDataParams, uint8_t *pCardResponse, uint8_t bCardRespLen)
	Performs second part of decryption of data received from Card. More...
phStatus_t	phhalHw_SamAV3_Cmd_SAM_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 **ppSamResponse, uint16_t *pSamRespLen)
	Performs key change for the specified current key to a new key. More...
phStatus_t	phhalHw_SamAV3_Cmd_SAM_CreateTMFilePICC (phhalHw_SamAV3_DataParams_t *pDataParams, uint8_t bOption, 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 **ppSamResponse, uint16_t *pSamRespLen)
	Performs creation of cryptogram for Transaction MAC file creation. More...

Sam AV3 command code for MIFARE DESFire S features.
#define	PHHAL_HW_SAMAV3_CMD_SAM_AUTHENTICATE_PICC_INS   0x0A
	Sam AV3 Instruction code for Cmd.SAM_AuthenticatePICC command.
#define	PHHAL_HW_SAMAV3_CMD_SAM_ISO_AUTHENTICATE_PICC_INS   0x8E
	Sam AV3 Instruction code for Cmd.SAM_IsoAuthenticatePICC command.
#define	PHHAL_HW_SAMAV3_CMD_SAM_CHANGE_KEY_PICC_INS   0xC4
	Sam AV3 Instruction code for Cmd.SAM_ChangeKeyPICC command.
#define	PHHAL_HW_SAMAV3_CMD_SAM_CREATE_TM_FILE_PICC_INS   0xC6
	Sam AV3 Instruction code for Cmd.SAM_CreateTMFilePICC command.

Detailed Description

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

Function Documentation

phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part1()

phStatus_t phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part1	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bKeyNo,
		uint8_t	bKeyVer,
		uint8_t	bAuthMode,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

Performs first part of encryption and decryption of data received from Card and to be sent to Card.

Here the Encrypted RndB data will be sent to Sam hardware. Sam hardware will Decrypt the data and Encrpyt RndA with RndB'. This encrypted RndA and RndB' will be returned to the caller for further transmission to the Card.

Returns

Status code

Return values

PH_ERR_SUCCESS_CHAINING	for successfull chaining operation.
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]	bKeyNo	[In] Reference key number to be used in hardware keystore.
[in]	bKeyVer	[In] Reference key version to be used in hardware keystore.
[in]	bAuthMode	[In] The type of key to be used for EV2 authentication. PHHAL_HW_CMD_SAMAV3_AUTH_MODE_EV2 PHHAL_HW_CMD_SAMAV3_AUTH_MODE_LRP
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length of diversification input used to diversify the key.
[in]	pCardResponse	[In] Encrypted RndB data returned by the card.
[in]	bCardRespLen	[In] Length of Encrypted RndB data.
[out]	ppSamResponse	[Out] Encrypted RndA and RndB' returned by the Sam hardware.
[out]	pSamRespLen	[Out] Length of Encrypted RndA and RndB' data.

phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part2()

phStatus_t phhalHw_SamAV3_Cmd_SAM_AuthenticatePICC_Part2	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bPiccErrorCode,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen,
		uint8_t *	pPDcap2,
		uint8_t *	pPCDcap2,
		uint8_t *	pStatusCode
	)

Performs second part of decryption of data received from Card.

Here the Encrypted RndA' data will be sent to Sam hardware. Sam hardware will Decrypt the data and extract PCD and PD Capabilities for EV2 First Auth and null in case of rest of Authentication modes. This PCD and PD information will be returned to the caller. Also the status code of Card will be returned to the caller in case of error.

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]	bPiccErrorCode	[In] Status code returned by the Card in case of failure else 90 for success.
[in]	pCardResponse	[In] Encrypted RndA' returned by the Sam hardware.
[in]	bCardRespLen	[In] Length of Encrypted RndA' data.
[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]	pStatusCode	[Out] Status code from Desfire PICC if available else zero.

phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part1()

phStatus_t phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part1	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bKeyNo,
		uint8_t	bKeyVer,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen,
		uint8_t **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

Performs first part of encryption and decryption of data received from Card and to be sent to Card.

Here the Encrypted RndB data will be sent to Sam hardware. Sam hardware will Decrypt the data and Encrpyt RndA with RndB'. This encrypted RndA and RndB' will be returned to the caller for further transmission to the Card.

Returns

Status code

Return values

PH_ERR_SUCCESS_CHAINING	for successfull chaining operation
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Options mentioned in the description. The options can be combined by bitwise oring. 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]	bKeyNo	[In] Reference key number to be used in hardware keystore.
[in]	bKeyVer	[In] Reference key version to be used in hardware keystore.
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length of diversification input used to diversify the key.
[in]	pCardResponse	[In] Encrypted RndB data returned by the card.
[in]	bCardRespLen	[In] Length of Encrypted RndB data.
[out]	ppSamResponse	[Out] Encrypted RndA and RndB' returned by the Sam hardware.
[out]	pSamRespLen	[Out] Length of Encrypted RndA and RndB' data.

phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part2()

phStatus_t phhalHw_SamAV3_Cmd_SAM_IsoAuthenticatePICC_Part2	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen
	)

Performs second part of decryption of data received from Card.

Here the Encrypted RndA' data will be sent to Sam hardware. Sam hardware will Decrypt the data and extract PCD and PD Capabilities for EV2 First Auth and null in case of rest of Authentication modes. This PCD and PD information will be returned to the caller. Also the status code of Card will be returned to the caller in case of error.

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]	pCardResponse	[In] Encrypted RndA' returned by the Sam hardware.
[in]	bCardRespLen	[In] Length of Encrypted RndA' data.

phhalHw_SamAV3_Cmd_SAM_ChangeKeyPICC()

phStatus_t phhalHw_SamAV3_Cmd_SAM_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 **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

Performs key change for the specified current key to a new key.

The crypto operation of the key to be changed will be calculated by SAM hardware. This crypto data will then sent to card to perform Change Key operations.

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
[in]	bKeySetNo	[In] Key set number to which the key to be changed belongs to.
[in]	bDFKeyNo	[In] Block number of the key available in the card. This will be used while exchanging the command with card. The lower nibble will be used for P2 information byte if command type is ChangeKey and the complete byte will be used if command type is 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]	ppSamResponse	[Out] Cryptogram holding key data.
[out]	pSamRespLen	[Out] Length of Cryptogram data.

phhalHw_SamAV3_Cmd_SAM_CreateTMFilePICC()

phStatus_t phhalHw_SamAV3_Cmd_SAM_CreateTMFilePICC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint8_t	bOption,
		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 **	ppSamResponse,
		uint16_t *	pSamRespLen
	)

Performs creation of cryptogram for Transaction MAC file creation.

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]	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]	ppSamResponse	[Out] Cryptogram holding Transaction MAC Key data.
[out]	pSamRespLen	[Out] Length of Cryptogram data.