SAM commands used for data processing. More...

Collaboration diagram for Data Processing:

Functions
phStatus_t	phhalHw_SamAV3_Cmd_SAM_ApplySM (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bCommMode, uint8_t bOffset, uint8_t bCmdCtrIncr, uint8_t pTxData, uint8_t bTxDataLen, uint8_t *ppRxData, uint16_t pRxDataLen)
	Applys the DESFire EV2 Secure Messaging in S-mode on the provided DESFire EV2 command according to the required mode and the currently activated session keys. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_RemoveSM (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bCommMode, uint8_t pTxData, uint8_t bTxDataLen, uint8_t *ppRxData, uint16_t pRxDataLen)
	Removes the DESFire EV2 Secure Messaging in S-mode ([22]) from the provided PICC response payload according to the required mode and the currently activated session keys. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_VerifyMAC (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bNum, uint8_t pTxData, uint8_t bTxDataLen)
	Verifies the MAC which was sent by the PICC or any other system based on the given MACed plain text data and the currently valid cryptographic key. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_GenerateMAC (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t bNum, uint8_t pTxData, uint8_t bTxDataLen, uint8_t *ppRxData, uint16_t pRxDataLen)
	Generates a MAC which is meant to be sent to the PICC or any other system based on the given plain text data and the currently valid cryptographic key. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_DecipherData (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t pEncData, uint8_t bEncDataLen, uint8_t pLength, uint8_t ppPlainData, uint16_t pPlainDataLen)
	Deciphers data packages sent by a PICC, any other system or a MIFARE card based on the currently valid cryptographic key and returns plain data to the host. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_EncipherData (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t pPlainData, uint8_t bPlainDataLen, uint8_t bOffset, uint8_t *ppEncData, uint16_t pEncDataLen)
	Enciphers data packages which are meant to be sent to a PICC or any other system based on the given plain text data and the currently valid cryptographic key. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_DecipherOfflineData (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t pEncData, uint8_t bEncDataLen, uint8_t *ppPlainData, uint16_t pPlainDataLen)
	Decrypts data received from any other system based on the given cipher text data and the currently valid cryptographic OfflineCrypto Key. More...

phStatus_t	phhalHw_SamAV3_Cmd_SAM_EncipherOfflineData (phhalHw_SamAV3_DataParams_t pDataParams, uint16_t wOption, uint8_t pPlainData, uint8_t bPlainDataLen, uint8_t *ppEncData, uint16_t pEncDataLen)
	Encrypts data received from any other system based on the given cipher text data and the currently valid cryptographic OfflineCrypto Key. More...

Sam AV3 command code for Sam Data Processing feature.
#define	PHHAL_HW_SAMAV3_CMD_SAM_APPLY_SM_INS 0xAE
	Sam AV3 Insturction code for SAM_ApplySM command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_REMOVE_SM_INS 0xAD
	Sam AV3 Insturction code for SAM_UndoSM command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_VERIFY_MAC_INS 0x5C
	Sam AV3 Insturction code for SAM_VerifyMac command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_GENERATE_MAC_INS 0x7C
	Sam AV3 Insturction code for SAM_GenerateMac command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_DECIPHER_DATA_INS 0xDD
	Sam AV3 Insturction code for SAM_DecipherData command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_ENCIPHER_DATA_INS 0xED
	Sam AV3 Insturction code for SAM_EncipherData command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_DECIPHER_OFFLINE_DATA_INS 0x0D
	Sam AV3 Insturction code for SAM_DecipherOfflineData command.

#define	PHHAL_HW_SAMAV3_CMD_SAM_ENCIPHER_OFFLINE_DATA_INS 0x0E
	Sam AV3 Insturction code for SAM_EncipherOfflineData command.

Option macros for Sam AV3 Data Processing Cmd.SAM_Apply_SM and Cmd.SAM_Remove_SM command.
#define	PHHAL_HW_SAMAV3_CMD_APPLY_SM_COMM_MODE_PLAIN 0x00
	Option mask for communication mode as plain for Cmd.SAM_Apply_SM command.

#define	PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_MAC 0x10
	Option mask for communication mode as MAC for Cmd.SAM_Apply_SM and Cmd.SAM_Remove_SM command.

#define	PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_FULL 0x30
	Option mask for communication mode as FULL for Cmd.SAM_Apply_SM and Cmd.SAM_Remove_SM command.

Option macros for Sam AV3 Data Processing Cmd.SAM_Apply_SM.
#define	PHHAL_HW_SAMAV3_CMD_APPLY_SM_EXCLUDE_OFFSET 0x00
	Option mask for not exchanging the Offset information for Cmd.SAM_Apply_SM command.

#define	PHHAL_HW_SAMAV3_CMD_APPLY_SM_INCLUDE_OFFSET 0x80
	Option mask for exchanging the Offset information for Cmd.SAM_Apply_SM command.

Option macros for Sam AV3 Data Processing Cmd.SAM_Verify_MAC and Cmd.SAM_GenerateMAC command.
#define	PHHAL_HW_SAMAV3_TRUNCATION_MODE_STANDARD 0x00
	Option mask for truncation mode as standard trunction.

#define	PHHAL_HW_SAMAV3_TRUNCATION_MODE_MFP 0x80
	Option mask for truncation mode as MFP trunction.

Option macros for Sam AV3 Data Processing Cmd.SAM_GenerateMAC command.
#define	PHHAL_HW_SAMAV3_GENERATE_MAC_INCLUDE_LC 0x80
	Option mask for inclusion of LC in the command frame.

Option macros for Sam AV3 Data Processing Cmd.SAM_Decipher_Data command.
#define	PHHAL_HW_SAMAV3_DECIPHER_LENGTH_EXCLUDE 0x00
	Option mask for excluding the length intformation in the command frame.

#define	PHHAL_HW_SAMAV3_DECIPHER_LENGTH_INCLUDE 0x80
	Option mask for including the length intformation in the command frame.

Detailed Description

SAM commands used for data processing.

Function Documentation

◆ phhalHw_SamAV3_Cmd_SAM_ApplySM()

phStatus_t phhalHw_SamAV3_Cmd_SAM_ApplySM	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCommMode,
		uint8_t	bOffset,
		uint8_t	bCmdCtrIncr,
		uint8_t *	pTxData,
		uint8_t	bTxDataLen,
		uint8_t **	ppRxData,
		uint16_t *	pRxDataLen
	)

Applys the DESFire EV2 Secure Messaging in S-mode on the provided DESFire EV2 command according to the required mode and the currently activated session keys.

The required protection mode is selected via the command parameter bCommMode.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Option for including the length information in command frame. PHHAL_HW_SAMAV3_CMD_APPLY_SM_EXCLUDE_OFFSET PHHAL_HW_SAMAV3_CMD_APPLY_SM_INCLUDE_OFFSET Buffering options. PH_EXCHANGE_DEFAULT PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	bCommMode	[In] Communication mode to be used. PHHAL_HW_SAMAV3_CMD_APPLY_SM_COMM_MODE_PLAIN PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_MAC PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_FULL
[in]	bOffset	[In] Command offset. Index of the first byte in data field of the PICC command data.
[in]	bCmdCtrIncr	[In] Command counter increment value. Value by which to increase the CmdCtr.
[in]	pTxData	[In] Plain data to be protected according to the communication mode specified.
[in]	bTxDataLen	[In] Length of plain data to be sent for protection.
[out]	ppRxData	[Out] The protected data returned by Sam according to communication mode specified.
[out]	pRxDataLen	[Out] Length of protected data returned.

◆ phhalHw_SamAV3_Cmd_SAM_RemoveSM()

phStatus_t phhalHw_SamAV3_Cmd_SAM_RemoveSM	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCommMode,
		uint8_t *	pTxData,
		uint8_t	bTxDataLen,
		uint8_t **	ppRxData,
		uint16_t *	pRxDataLen
	)

Removes the DESFire EV2 Secure Messaging in S-mode ([22]) from the provided PICC response payload according to the required mode and the currently activated session keys.

The required protection mode is selected via the command parameter bCommMode.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	bCommMode	[In] Communication mode to be used. PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_MAC PHHAL_HW_SAMAV3_CMD_APPLY_REMOVE_SM_COMM_MODE_FULL
[in]	pTxData	[In] The complete data received form the PICC including the status code.
[in]	bTxDataLen	[In] Length of data available in TxData buffer.
[out]	ppRxData	[Out] The plain data returned by Sam according to communication mode specified.
[out]	pRxDataLen	[Out] Length of plain data returned.

◆ phhalHw_SamAV3_Cmd_SAM_VerifyMAC()

phStatus_t phhalHw_SamAV3_Cmd_SAM_VerifyMAC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bNum,
		uint8_t *	pTxData,
		uint8_t	bTxDataLen
	)

Verifies the MAC which was sent by the PICC or any other system based on the given MACed plain text data and the currently valid cryptographic key.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	bNum	[In] Type of truncation mode to be applied if AES key type is used. PHHAL_HW_SAMAV3_TRUNCATION_MODE_STANDARD PHHAL_HW_SAMAV3_TRUNCATION_MODE_MFP Number of MAC bytes to check in the plain data buffer. Number of Bytes should be combined with one of the above two options.
[in]	pTxData	[In] Plain data including the MAC to be checked.
[in]	bTxDataLen	[In] Length of data available in TxData buffer.

◆ phhalHw_SamAV3_Cmd_SAM_GenerateMAC()

phStatus_t phhalHw_SamAV3_Cmd_SAM_GenerateMAC	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bNum,
		uint8_t *	pTxData,
		uint8_t	bTxDataLen,
		uint8_t **	ppRxData,
		uint16_t *	pRxDataLen
	)

Generates a MAC which is meant to be sent to the PICC or any other system based on the given plain text data and the currently valid cryptographic key.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data. PHHAL_HW_SAMAV3_GENERATE_MAC_INCLUDE_LC should be used for inclusion of LC when PH_EXCHANGE_BUFFER_FIRST is used and TxDataLen is not available but TxDataLen is part of PH_EXCHANGE_BUFFER_CONT or PH_EXCHANGE_BUFFER_LAST.
[in]	bNum	[In] Type of truncation mode to be applied if AES key type is used. PHHAL_HW_SAMAV3_TRUNCATION_MODE_STANDARD PHHAL_HW_SAMAV3_TRUNCATION_MODE_MFP Number of MAC bytes to check in the plain data buffer. Number of Bytes should be combined with one of the above two options.
[in]	pTxData	[In] Plain data to be maced. Can be null if there is no data.
[in]	bTxDataLen	[In] Length of input data. Can be zero if there is no Plain data.
[out]	ppRxData	[Out] The generated MAC returned by Sam hardware.
[out]	pRxDataLen	[Out] Length of Maced data returned.

◆ phhalHw_SamAV3_Cmd_SAM_DecipherData()

phStatus_t phhalHw_SamAV3_Cmd_SAM_DecipherData	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t *	pEncData,
		uint8_t	bEncDataLen,
		uint8_t *	pLength,
		uint8_t **	ppPlainData,
		uint16_t *	pPlainDataLen
	)

Deciphers data packages sent by a PICC, any other system or a MIFARE card based on the currently valid cryptographic key and returns plain data to the host.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Option for including the length information in command frame. PHHAL_HW_SAMAV3_DECIPHER_LENGTH_EXCLUDE PHHAL_HW_SAMAV3_DECIPHER_LENGTH_INCLUDE Buffering options. PH_EXCHANGE_DEFAULT PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	pEncData	[In] Encrypted data to be deciphered.
[in]	bEncDataLen	[In] Length of Encrypted data.
[in]	pLength	[In] Overall length of encrypted input data. This 3 byte value is only used if indicated by wOption.
[out]	ppPlainData	[Out] Deciphered data returned by Sam hardware.
[out]	pPlainDataLen	[Out] Length of deciphered data.

◆ phhalHw_SamAV3_Cmd_SAM_EncipherData()

phStatus_t phhalHw_SamAV3_Cmd_SAM_EncipherData	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t *	pPlainData,
		uint8_t	bPlainDataLen,
		uint8_t	bOffset,
		uint8_t **	ppEncData,
		uint16_t *	pEncDataLen
	)

Enciphers data packages which are meant to be sent to a PICC or any other system based on the given plain text data and the currently valid cryptographic key.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	pPlainData	[In] Data to be enciphered.
[in]	bPlainDataLen	[In] Length of input data.
[in]	bOffset	[In] Offset into the input data indicating the first data byte to be enciphered.
[out]	ppEncData	[Out] Enciphered data returned by Sam hardware.
[out]	pEncDataLen	[Out] Length of enciphered data.

◆ phhalHw_SamAV3_Cmd_SAM_DecipherOfflineData()

phStatus_t phhalHw_SamAV3_Cmd_SAM_DecipherOfflineData	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t *	pEncData,
		uint8_t	bEncDataLen,
		uint8_t **	ppPlainData,
		uint16_t *	pPlainDataLen
	)

Decrypts data received from any other system based on the given cipher text data and the currently valid cryptographic OfflineCrypto Key.

The valid key has been activated using a valid key activation (Cmd.SAM_ActivateOfflineKey).

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	pEncData	[In] Encrypted data to be deciphered.
[in]	bEncDataLen	[In] Length of Encrypted data.
	ppPlainData	[Out Deciphered data returned by Sam hardware.
[out]	pPlainDataLen	[Out] Length of deciphered data.

◆ phhalHw_SamAV3_Cmd_SAM_EncipherOfflineData()

phStatus_t phhalHw_SamAV3_Cmd_SAM_EncipherOfflineData	(	phhalHw_SamAV3_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t *	pPlainData,
		uint8_t	bPlainDataLen,
		uint8_t **	ppEncData,
		uint16_t *	pEncDataLen
	)

Encrypts data received from any other system based on the given cipher text data and the currently valid cryptographic OfflineCrypto Key.

The valid key has been activated using a valid key activation (Cmd.SAM_ActivateOfflineKey).

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
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 PH_EXCHANGE_BUFFER_FIRST PH_EXCHANGE_BUFFER_CONT PH_EXCHANGE_BUFFER_LAST PH_EXCHANGE_TXCHAINING PH_EXCHANGE_TXCHAINING should be used to exchange chunks of data.
[in]	pPlainData	[In] Plain data to be enciphered.
[in]	bPlainDataLen	[In] Length of plain data.
[out]	ppEncData	[Out] Enciphered data returned by Sam hardware.
[out]	pEncDataLen	[Out] Length of enciphered data.

Functions

Sam AV3 command code for Sam Data Processing feature.

Option macros for Sam AV3 Data Processing Cmd.SAM_Apply_SM and Cmd.SAM_Remove_SM command.

Option macros for Sam AV3 Data Processing Cmd.SAM_Apply_SM.

Option macros for Sam AV3 Data Processing Cmd.SAM_Verify_MAC and Cmd.SAM_GenerateMAC command.

Option macros for Sam AV3 Data Processing Cmd.SAM_GenerateMAC command.

Option macros for Sam AV3 Data Processing Cmd.SAM_Decipher_Data command.

Detailed Description

Function Documentation

◆ phhalHw_SamAV3_Cmd_SAM_ApplySM()

◆ phhalHw_SamAV3_Cmd_SAM_RemoveSM()

◆ phhalHw_SamAV3_Cmd_SAM_VerifyMAC()

◆ phhalHw_SamAV3_Cmd_SAM_GenerateMAC()

◆ phhalHw_SamAV3_Cmd_SAM_DecipherData()

◆ phhalHw_SamAV3_Cmd_SAM_EncipherData()

◆ phhalHw_SamAV3_Cmd_SAM_DecipherOfflineData()

◆ phhalHw_SamAV3_Cmd_SAM_EncipherOfflineData()