S_Mode

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

Collaboration diagram for S_Mode:

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

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part1 (phhalHw_Sam_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 PICC and to be sent to PICC. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part2 (phhalHw_Sam_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 PICC. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part1 (phhalHw_Sam_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 PICC and to be sent to PICC. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part2 (phhalHw_Sam_DataParams_t *pDataParams, uint8_t *pCardResponse, uint8_t bCardRespLen)
	Performs second part of decryption of data received from PICC. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_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 **ppSamResponse, uint16_t *pSamRespLen)
	Performs key change for the specified current key to a new key. More...
phStatus_t	phhalHw_Sam_Cmd_SAM_CreateTMFilePICC (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bOption, 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 **ppSamResponse, uint16_t *pSamRespLen)
	The SAM_CreateTMFilePICC command supports the procedure to create a Transaction MAC File in the PICC in S-mode from a key stored in the SAM. More...

Detailed Description

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

Function Documentation

phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part1()

phStatus_t phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part1	(	phhalHw_Sam_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 PICC and to be sent to PICC.

Here the Encrypted RndB data will be sent to SAM. SAM will Decrypt the data and Encrypt RndA with RndB'. This encrypted RndA and RndB' will be returned to the caller for further transmission to the PICC.

Note

• Post calling this interface it's must to call AuthenticatePICC Part2 to place SAM into proper completion state if Chaining Status is returned from Library. Otherwise error will be returned by SAM for any subsequent commands.
• If Chaining Status is not returned from Library, no need to call AuthenticatePICC Part2 interface.

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pDivInput, pCardResponse and pSamRespLen 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]	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]	bAuthMode	[In] The type of key to be used for EV2 authentication. EV2 authentication LRP authentication
[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.
[in]	pCardResponse	[In] Encrypted Challenge (RndB) data returned by the PICC. If targeting D40 & EV1 authentication with 2TDEA Key: 8 bytes as E(Kx,RndB) If targeting D40 & EV1 authentication with 3TDEA, AES Key or if targeting EV2 authentication: 16 bytes as E(Kx,RndB) If targeting LRP authentication: 16 bytes as RndB
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse buffer.
[out]	ppSamResponse	[Out] Encrypted PCD Challenge (RndA and RndB') returned by the SAM. One of the following will be available, If targeting D40 & EV1 authentication with 2TDEA Key: 16 bytes as E(Kx,RndA || RndB') If targeting D40 & EV1 authentication with 3TDEA, AES Key or if targeting EV2 authentication: 32 bytes as E(Kx,RndA || RndB') If targeting LRP authentication: 32 bytes as RndA || MAC(Km, RndA||RndB)
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part2()

phStatus_t phhalHw_Sam_Cmd_SAM_AuthenticatePICC_Part2	(	phhalHw_Sam_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 PICC.

Here the Encrypted RndA' data will be sent to SAM. SAM 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 PICC will be returned to the caller in case of error.

Note

This interface should be called only if AuthenticatePICC Part1 returns Chaining Status.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pCardResponse, pPDcap2 pPCDcap2 and pPiccRetCode are NULL.
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 PICC in case of failure else 00h for success.
[in]	pCardResponse	[In] Encrypted RndA' returned by the SAM. One of the following, If targeting EV2 first authentication: 32 bytes as E(Kx,TI||RndA'||PDcap2||PCDcap2) If targeting LRP first authentication: 32 bytes as E(Ke, TI||PDCap2||PCDCap2) || MAC(Km, RndB || RndA E(Ke, TI||PDCap2||PCDCap2)) If targeting LRP non-first authentication: 16 bytes as MAC(Km, RndB || RndA) If targeting D40 & EV1 authentication with 2TDEA Key: 8 or 16 bytes as E(Kx,RndA')
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse 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]	pStatusCode	[Out] Status code from MIFARE DESFire PICC if available else zero.

phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part1()

phStatus_t phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part1	(	phhalHw_Sam_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 PICC and to be sent to PICC.

Here the Encrypted RndB data will be sent to SAM. SAM will Decrypt the data and Encrypt RndA with RndB'. This encrypted RndA and RndB' will be returned to the caller for further transmission to the PICC.

Note

• Post calling this interface it's must to call IsoAuthenticatePICC Part2 to place SAM into proper completion state if Chaining Status is returned from Library. Otherwise error will be returned by SAM for any subsequent commands.
• If Chaining Status is not returned from Library, no need to call IsoAuthenticatePICC Part2 interface.

Return values

PH_ERR_SUCCESS_CHAINING	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pDivInput, pCardResponse and pSamRespLen 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 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]	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]	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.
[in]	pCardResponse	[In] PICC challenge in clear as received from PICC's Cmd.ISOGetChallenge. If targeting TDEA Key: 8 bytes encrypted Challenge If targeting 3TDEA or AES Key: 16 bytes encrypted Challenge
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse buffer.
[out]	ppSamResponse	[Out] Encrypted PCD Challenge (RndA and RndB') and response returned by the SAM. One of the following will be available. If targeting TDEA Key: 24 bytes as E(Kx, RPCD1 || RPICC1 ) || RPCD2 If targeting 3TDEA or AES Key: 48 bytes as E(Kx, RPCD1 || RPICC1 ) || RPCD2
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part2()

phStatus_t phhalHw_Sam_Cmd_SAM_IsoAuthenticatePICC_Part2	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t *	pCardResponse,
		uint8_t	bCardRespLen
	)

Performs second part of decryption of data received from PICC.

Here the Encrypted RndA' data will be sent to SAM. SAM 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 PICC will be returned to the caller in case of error.

Note

This interface should be called only if IsoAuthenticatePICC Part1 returns Chaining Status.

Returns

Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	pCardResponse	[In] PICC encrypted response as received from Cmd.ISOInternalAuthenticate. One of the following, If targeting TDEA Key: 16 bytes as E(Kx, RPICC2 || RRPCD2 ) If targeting 3TDEA or AES Key: 32 bytes as E(Kx, RPICC2 || RRPCD2 )
[in]	bCardRespLen	[In] Length of bytes available in pCardResponse buffer.

phhalHw_Sam_Cmd_SAM_ChangeKeyPICC()

phStatus_t phhalHw_Sam_Cmd_SAM_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 **	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.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pDivInput and pSamRespLen 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. 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] Block number of the key available in the PICC. This will be used while exchanging the command with PICC. The lower nibble will be used for P2 information byte if bConfig has Cmd.ChangeKey. Complete byte will be used if bConfig has 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]	ppSamResponse	[Out] Cryptogram holding key data.
[out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.

phhalHw_Sam_Cmd_SAM_CreateTMFilePICC()

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

The SAM_CreateTMFilePICC command supports the procedure to create a Transaction MAC File in the PICC in S-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 pSamRespLen 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]	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. 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]	ppSamResponse	[Out] Cryptogram holding Transaction MAC Key data.
    [out]	pSamRespLen	[Out] Length of bytes available in ppSamResponse buffer.