04_DataProcessing

Implementation of SAM Data Processing commands. More...

Collaboration diagram for 04_DataProcessing:

Modules
	Defines
	Definitions for SAM Data Processing commands.

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_ApplySM (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wOption, uint8_t bCommMode, uint8_t bOffset, uint8_t bCmdCtrIncr, uint8_t *pData, uint8_t bDataLen, uint8_t **ppResponse, uint16_t *pRespLen)
	Apply the DESFire EVx (EV2 or higher) Secure Messaging in S-mode on the provided DESFire EVx (EV2 or higher) command according to the required mode and the currently activated session keys. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_RemoveSM (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wOption, uint8_t bCommMode, uint8_t *pData, uint8_t bDataLen, uint8_t **ppResponse, uint16_t *pRespLen)
	Removes the DESFire EVx (EV2 or higher) Secure Messaging in S-mode from the provided PICC response payload according to the required mode and the currently activated session keys. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_VerifyMAC (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wOption, uint8_t bNum, uint8_t *pData, uint8_t bDataLen)
	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_Sam_Cmd_SAM_GenerateMAC (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wOption, uint8_t bNum, uint8_t *pData, uint8_t bDataLen, uint8_t **ppResponse, uint16_t *pRespLen)
	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_Sam_Cmd_SAM_DecipherData (phhalHw_Sam_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_Sam_Cmd_SAM_EncipherData (phhalHw_Sam_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_Sam_Cmd_SAM_DecipherOfflineData (phhalHw_Sam_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_Sam_Cmd_SAM_EncipherOfflineData (phhalHw_Sam_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...

Detailed Description

Implementation of SAM Data Processing commands.

Function Documentation

phhalHw_Sam_Cmd_SAM_ApplySM()

phStatus_t phhalHw_Sam_Cmd_SAM_ApplySM	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCommMode,
		uint8_t	bOffset,
		uint8_t	bCmdCtrIncr,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

Apply the DESFire EVx (EV2 or higher) Secure Messaging in S-mode on the provided DESFire EVx (EV2 or higher) 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.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pData and pRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Refer below for Option to be used. Offset (bOffset is not exchanged to SAM) Offset (bOffset is exchanged to SAM) Buffering options. Ored with above options. 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
[in]	bCommMode	[In] Communication mode to be used. Communication mode as Plain Communication mode as MAc Communication mode as 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]	pData	[In] Plain data to be protected according to the communication mode specified.
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] The protected data returned by Sam according to communication mode specified.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.

phhalHw_Sam_Cmd_SAM_RemoveSM()

phStatus_t phhalHw_Sam_Cmd_SAM_RemoveSM	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bCommMode,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

Removes the DESFire EVx (EV2 or higher) Secure Messaging in S-mode 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.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pData and pRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options to exchange data to SAM and receive data from 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
[in]	bCommMode	[In] Communication mode to be used. Communication mode as MAc Communication mode as Full
[in]	pData	[In] The complete data received form the PICC including the status code.
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] The plain data returned by Sam according to communication mode specified.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.

phhalHw_Sam_Cmd_SAM_VerifyMAC()

phStatus_t phhalHw_Sam_Cmd_SAM_VerifyMAC	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bNum,
		uint8_t *	pData,
		uint8_t	bDataLen
	)

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.

• The valid key has been activated using a valid PICC authentication (SAM_AuthenticatePICC , SAM_IsoAuthenticatePICC) in case of a PICC key or using a valid key activation (SAM_ActivateOfflineKey) in case of an OfflineCrypto Key
• The applied MAC algorithm depends on the key type. The command can be used for verifying only a part, up to the full MAC. The number of MAC bytes to be verified is defined by parameter bNum. By default the standard truncation is expected. For AES key types (including KeyType.AES_128LRP), also the truncation as used by a.o. the MIFARE Plus Secure Messaging can be applied. This option for MFP Truncation is not allowed with a key that has the option 'Keep IV' (SET bit 2) set.
• In OfflineCrypto PICC State, if the targeted key is of KeyType.AES_128LRP, SAM_Verify_MAC shall apply KeyID.LRPUpdate or KeyID.LRPMACUpdate, if respectively one or two updated keys were generated with SAM_ActivateOfflineKey.
• In OfflineCrypto PICC State, if activated key from KST is referencing a KUC, SAM_Verify_MAC increments the KUC associated to the targeted key before any crypto processing.
• Note that SAM_Verify_MAC supports the verification of a MAC over zero-byte input length messages. In that case the Data field of the APDU will just contain the MAC.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pData is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options to exchange data to SAM and receive data from 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
[in]	bNum	[In] Type of truncation mode to be applied if AES key type is used. Standard truncation MFP truncation Number of MAC bytes (bNum) to be verified. Should be combined with one of the above options. 0x01 - 0x08: (3)DES key types 0x01 - 0x10: AES key types 0x00: Default number of bytes (depending on key type)
[in]	pData	[In] Plain data including the MAC to be checked.
[in]	bDataLen	[In] Length of bytes available in pData buffer.

phhalHw_Sam_Cmd_SAM_GenerateMAC()

phStatus_t phhalHw_Sam_Cmd_SAM_GenerateMAC	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wOption,
		uint8_t	bNum,
		uint8_t *	pData,
		uint8_t	bDataLen,
		uint8_t **	ppResponse,
		uint16_t *	pRespLen
	)

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.

• The valid key has been activated using a valid PICC authentication (SAM_AuthenticatePICC , SAM_IsoAuthenticatePICC) in case of a PICC key or using a valid key activation (SAM_ActivateOfflineKey) in case of an OfflineCrypto Key.
• The applied MAC algorithm depends on the key type. The command can be used for creating only a part, up to the full MAC. The number of MAC bytes to be generated is defined by parameter bNum. By default the standard truncation is applied. For AES key types (including KeyType.AES_128LRP), also the truncation as used by a.o. the MIFARE Plus Secure Messaging can be applied. This option for MFP Truncation is not allowed with a key that has the option 'Keep IV' (SET bit 2) set.
• In OfflineCrypto PICC State, if the targeted key is of KeyType.AES_128LRP, SAM_Generate_MAC shall apply KeyID.LRPUpdate or KeyID.LRPMACUpdate, if respectively one or two updated keys were generated with SAM_ActivateOfflineKey.
• In OfflineCrypto PICC State, if activated key from KST is referencing a KUC, SAM_Generate_MAC increments the KUC associated to the targeted key before any crypto processing.
• Note that SAM_Generate_MAC supports the generation of a MAC over zero-byte input length messages. In that case the LC and Data fields of the command APDU will be absent.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pData and pRespLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. 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 Include LC should be used for inclusion of LC when First Data Chunk is used and bDataLen is not available but bDataLen is part of Intermediate Data Chunk or Last Data Chunk.
[in]	bNum	[In] Type of truncation mode to be applied if AES key type is used. used. Standard truncation MFP truncation Number of MAC bytes (bNum) to be processed. Should be combined with one of the above options. 0x01 - 0x08: (3)DES key types 0x01 - 0x10: AES key types 0x00: Default number of bytes (depending on key type)
[in]	pData	[In] Plain data to be maced. Can be null if there is no data.
[in]	bDataLen	[In] Length of bytes available in pData buffer.
[out]	ppResponse	[Out] The generated MAC returned by SAM.
[out]	pRespLen	[Out] Length of bytes available in ppResponse buffer.

phhalHw_Sam_Cmd_SAM_DecipherData()

phStatus_t phhalHw_Sam_Cmd_SAM_DecipherData	(	phhalHw_Sam_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.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pEncData and pPlainDataLen is NULL.
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. Length information (pLength) will not be exchanged Length information (pLength) will be exchanged Buffering options. Ored with above options. 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
[in]	pEncData	[In] Encrypted data to be deciphered.
[in]	bEncDataLen	[In] Length of bytes available in pEncData buffer.
[in]	pLength	[In] Overall length of encrypted input data. This 3 byte value is only used if wOption has Length information (pLength) will be exchanged.
[out]	ppPlainData	[Out] Deciphered data returned by SAM.
[out]	pPlainDataLen	[Out] Length of bytes available in ppResponse buffer.

phhalHw_Sam_Cmd_SAM_EncipherData()

phStatus_t phhalHw_Sam_Cmd_SAM_EncipherData	(	phhalHw_Sam_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.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	bPlainDataLen and pEncDataLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. 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
[in]	pPlainData	[In] Plain Data to be enciphered.
[in]	bPlainDataLen	[In] Length of bytes available in pPlainData buffer.
[in]	bOffset	[In] Offset into the input data indicating the first data byte to be enciphered.
[out]	ppEncData	[Out] Enciphered data returned by SAM.
[out]	pEncDataLen	[Out] Length of bytes available in ppEncData buffer.

phhalHw_Sam_Cmd_SAM_DecipherOfflineData()

phStatus_t phhalHw_Sam_Cmd_SAM_DecipherOfflineData	(	phhalHw_Sam_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 (SAM_ActivateOfflineKey).

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pEncData and pPlainDataLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. 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
[in]	pEncData	[In] Encrypted data to be deciphered.
[in]	bEncDataLen	[In] Length of bytes available in pEncData buffer.
	ppPlainData	[Out Deciphered data returned by SAM.
[out]	pPlainDataLen	[Out] Length of bytes available in ppPlainData buffer.

phhalHw_Sam_Cmd_SAM_EncipherOfflineData()

phStatus_t phhalHw_Sam_Cmd_SAM_EncipherOfflineData	(	phhalHw_Sam_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 (SAM_ActivateOfflineKey).

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_SUCCESS_CHAINING	Operation successful, chaining ongoing.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pEncData and pPlainDataLen is NULL.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wOption	[In] Buffering options. 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
[in]	pPlainData	[In] Plain data to be enciphered.
[in]	bPlainDataLen	[In] Length of bytes available in pPlainData buffer.
[out]	ppEncData	[Out] Enciphered data returned by SAM.
[out]	pEncDataLen	[Out] Length of bytes available in ppEncData buffer.