Implementation of SAM Host Communication commands. More...

Collaboration diagram for 01_HostCommunication:

Modules
	Defines
	Definitions for SAM Host Authentication commands.

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_LockUnlock (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bLockType, uint16_t wRdKeyNo, uint16_t wRdKeyVer, uint8_t bSamKeyNo, uint8_t bSamKeyVer, uint8_t bUnlockKeyNo, uint8_t bUnlockKeyVer, uint32_t dwMaxChainBlocks)
	Activate, Lock or Unlock the SAM. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_AuthenticateHost (phhalHw_Sam_DataParams_t *pDataParams, uint8_t bHostMode, uint16_t wRdKeyNo, uint16_t wRdKeyV, uint8_t bSamKeyNo, uint8_t bSamKeyV)
	Mutual 3-pass authentication between Host and SAM. More...

Detailed Description

Implementation of SAM Host Communication commands.

Function Documentation

phStatus_t phhalHw_Sam_Cmd_SAM_LockUnlock	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bLockType,
		uint16_t	wRdKeyNo,
		uint16_t	wRdKeyVer,
		uint8_t	bSamKeyNo,
		uint8_t	bSamKeyVer,
		uint8_t	bUnlockKeyNo,
		uint8_t	bUnlockKeyVer,
		uint32_t	dwMaxChainBlocks
	)

Activate, Lock or Unlock the SAM.

The SAM_LockUnlock command is used to modify the SAM Global State for all active LC's, and to activate the SAM.
It is implemented by mean of a mutual authentication between the SAM and host system.
Such authentication proves that both the SAM and the host contain the same secret, namely the AES authentication key Kx.
Only authorized Host systems are allowed to change the SAM Global State.
Starting SAM_LockUnlock command invalidates any other existing authentication (incl. Offline Key Activation) on any of the logical channels.
If key entry (SAMKey) is not of AES_128, AES_192 or AES_256 key, no authentication is possible with this key entry.
If key entry (SAMKey != MasterKey) is not a LockKey, no authentication is possible with this key entry.
During the first part of the authentication, the host indicates whether the SAM shall execute the SAM Activation, the lock or the unlock operation.
The activation is used to protect the SAM against tampering before delivery to and to provide a way to configure\ some settings of the SAM.

Note

It's important to perform Host Authentication after successful LockUnlock operation to set the new session keys.
Host Authentication is required because, LockUnlock interface will utilize the same CryptoParams which was utilized by Host Authentication interface.
Since the CryptoParams are common, the keys will be updated by LockUnlock interface and the existing Host Authentication session keys will not be available.

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_KEY	If wRdKeyNo is not one of AES128, AES192 or AES256
PH_ERR_LENGTH_ERROR	If response length received is not as expected for part1, part2 and part3.
PH_ERR_AUTH_ERROR	The response for RndA is not equal to sent RndA
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bLockType	[In] Sub Command type. Unlock Lock without specifying unlock key Lock with specifying unlock key Activate MIFARE SAM Unlock Programmable Logic
[in]	wRdKeyNo	[In] Key reference number to be used in Software KeyStore.
[in]	wRdKeyVer	[In] Key version to be used in Software KeyStore.
[in]	bSamKeyNo	[In] Key reference number in SAM. One of the following, NVM Key: 0x00 - 0x07 PL Unlock Key: 0xF0
[in]	bSamKeyVer	[In] Key version to be used in SAM.
[in]	bUnlockKeyNo	[In] Unlock Key Number to be used in SAM (only used when bLockType = Lock with specifying unlock key).
[in]	bUnlockKeyVer	[In] Unlock Key Version to be used in SAM (only used when bLockType = Lock with specifying unlock key).
[in]	dwMaxChainBlocks	[In] Maximal message size under command chaining in MAC or Full Protection (only used when bLockType = Activate MIFARE SAM).

phStatus_t phhalHw_Sam_Cmd_SAM_AuthenticateHost	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bHostMode,
		uint16_t	wRdKeyNo,
		uint16_t	wRdKeyV,
		uint8_t	bSamKeyNo,
		uint8_t	bSamKeyV
	)

Mutual 3-pass authentication between Host and SAM.

The SAM_AuthenticateHost will perform a mutual authentication for a specific LC between the SAM and host. system. Such an authentication proves that both the SAM and the host contain the same secret, namely the AES authentication key Kx.
Starting SAM_AuthenticateHost command invalidates any other existing authentication (incl. Offline Key Activation) in the LC.
If the authentication key entry (SAMKey) is not of AES_128, AES_192 or AES_256, no authentication is possible with this key entry.
If the authentication key entry (SAMKey != MasterKey) is not a AuthKey, no authentication is possible with this key entry.
SAM_AuthenticateHost is executed in three parts.
- During the first part of the authentication, the host indicates the AES authentication key (Kx) and the selected protection mode (HostMode) to be used by the established SAC: Plain, MAC or Full mode.
- If an invalid key entry and/or key version are referenced, or if the key to be used is not an AuthKey (or an AuthLockKey in the SAM Locked State), an error is returned.
- If the provided HostMode is not one of the expected values, an error is returned and the protocol is aborted.

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_KEY	If wRdKeyNo is not one of AES128, AES192 or AES256
PH_ERR_LENGTH_ERROR	If response length received is not as expected for part1, part2 and part3.
PH_ERR_AUTH_ERROR	The response for RndA is not equal to sent RndA
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bHostMode	[In] Type of Protection mode to be applied. Protection Mode as PLAIN (Data in PLAIN) Protection Mode as MAC (Data in PLAIN and MAC Available) Protection Mode as FULL (Data Crypted and MAC available)
[in]	wRdKeyNo	[In] Key reference number to be used in Software KeyStore.
[in]	wRdKeyV	[In] Key version to be used in Software KeyStore.
[in]	bSamKeyNo	[In] Key reference number in SAM.
[in]	bSamKeyV	[In] Key version to be used in SAM.