SAM commands used for host communication and security related configuration. More...

Collaboration diagram for Security and Configuration:

Macros
#define	PHHAL_HW_SAMAV2_AUTH_FIRST_PART_MASK 0x10
	Mask to specify first part of Authenticate Host.

#define	PHHAL_HW_SAMAV2_AUTH_SECOND_PART_MASK 0x20
	Mask to specify second part of Authenticate Host.

#define	PHHAL_HW_SAMAV2_AUTH_THIRD_PART_MASK 0x40
	Mask to specify third part of Authenticate Host.

#define	PHHAL_HW_SAMAV2_CMD_SELECT_APPLICATION_DATA_LENGTH 0x03
	data length for SAM_KillAuthentication command

#define	PHHAL_HW_SAMAV2_CMD_LOAD_INIT_VECTOR_DATA_LENGTH_MIN 0x08
	Minimum data length for SAM_KillAuthentication command.

#define	PHHAL_HW_SAMAV2_CMD_LOAD_INIT_VECTOR_DATA_LENGTH_MAX 0x10
	Maximum data length for SAM_KillAuthentication command.

#define	PHHAL_HW_SAMAV2_CMD_GET_VERSION_DATA_LENGTH 0x00
	CMD length of GetVersion command.

#define	PHHAL_HW_SAMAV2_CMD_GET_VERSION_RESPONSE_LENGTH 0x1F
	Response length for GetVersion command.

#define	PHHAL_HW_SAMAV2_CMD_GET_VERSION_RESPONSE_UID_OFFSET 0x0E
	Offset of first UID byte field in the Version field.

#define	PHHAL_HW_SAMAV2_CMD_GET_VERSION_RESPONSE_HOSTMODE_POS 0x1E
	Offset of first UID byte field in the Version field.

#define	PHHAL_HW_SAMAV2_CMD_SLEEP_DATA_LENGTH 0x00
	CMD length of Sleep command.

#define	PHHAL_HW_SAMAV2_CMD_SLEEP_RESPONSE_LENGTH 0x00
	Response length for Sleep command.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_MIN_DATA_LENGTH 0x02
	Minimum CMD length of LockUnlock command.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_MAX_DATA_LENGTH 0x05
	Maximum CMD length of LockUnlock command.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_RESPONSE1_LENGTH 0x0C
	Response length for LockUnlock command.

#define	PHHAL_HW_SAMAV2_CMD_ISO_EXTERNAL_AUTHENTICATE_MIN_DATA_LENGTH 0x02
	Minimum CMD length for SAM_IsoExternalAuthenticate command.

#define	PHHAL_HW_SAMAV2_CMD_ACTIVATE_OFFLINE_KEY_MIN_DATA_LENGTH 0x02
	Minimum CMD length for SAM_ActivateOfflineKey command.

Functions
phStatus_t	phhalHw_SamAV2_Cmd_SAM_DisableCrypto (phhalHw_SamAV2_DataParams_t *pDataParams, uint16_t wProMas)
	Disable cryto-related features of the SAM PERMANENTLY AND IRREVERSIBLY. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_LockUnlock (phhalHw_SamAV2_DataParams_t *pDataParams, uint8_t bMode, uint16_t wRdKeyNo, uint16_t wRdKeyV, uint8_t bSamKeyNo, uint8_t bSamKeyV, uint8_t bUnlockKeyNo, uint8_t bUnlockKeyV, uint32_t bMaxChainBlocks)
	Lock or Unlock the SAM. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_AuthenticateHost (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bAuthType_HostMode, uint16_t wRdKeyNo, uint16_t wRdKeyV, uint8_t bSamKeyNo, uint8_t bSamKeyV, uint8_t pDivInput, uint8_t bDivInputLength)
	Mutual 2-pass-AV1 or 3-pass-AV2 authentication between Host and SAM. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_ActivateOfflineKey (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bKeyNo, uint8_t bKeyV, uint8_t pDivInput, uint8_t bDivInputLength)
	Activation of an OfflineCrypto or an OfflineChange Key. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_LoadInitVector (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t pInitVector, uint8_t bInitVectorLength)
	Load an Init Vector for the next cryptographic operation into the SAM. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_KillAuthentication (phhalHw_SamAV2_DataParams_t *pDataParams, uint8_t bOption)
	Kill all active authentications in this logical channel. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_SelectApplication (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t pDF_Aid)
	Select an application by the DF_AID. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_GetChallenge (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bExpL, uint8_t pRnd)
	Executes the first part of an ISO compliant authentication procedure (AV1) or fetches a random number from the SAM (AV2). More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_IsoExternalAuthenticate (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bKeyNo, uint8_t bKeyV, uint8_t pEncRnd, uint8_t bEncRndLength)
	Executes the second part of an ISO compliant authentication procedure. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_IsoInternalAuthenticate (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t pRPcd2, uint8_t bRPcd2Length, uint8_t *pEncResp, uint16_t pEncRespLength)
	Executes the third part of an ISO compliant authentication procedure. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_GetVersion (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t pVersion, uint8_t *pVersionLength)
	Get version information from the SAM. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_Sleep (phhalHw_SamAV2_DataParams_t *pDataParams)
	Set the SAM into power down mode. More...

Sam AV2 command code for Sam Security and configuration feature.
#define	PHHAL_HW_SAMAV2_CMD_DISABLE_CRYPTO 0xDC
	CMD Byte for SAM_DisableCrypto command.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_INS 0x10
	CMD Byte for LockUnlock command.

#define	PHHAL_HW_SAMAV2_CMD_AUTHENTICATE_HOST_INS 0xA4
	CMD Byte for SAM_AuthenticateHost command.

#define	PHHAL_HW_SAMAV2_CMD_ACTIVATE_OFFLINE_KEY_INS 0x01
	CMD Byte for SAM_ActivateOfflineKey command.

#define	PHHAL_HW_SAMAV2_CMD_LOAD_INIT_VECTOR_INS 0x71
	CMD Byte for SAM_SelectApplication command.

#define	PHHAL_HW_SAMAV2_CMD_KILL_AUTHENTICATION_INS 0xCA
	CMD Byte for SAM_KillAuthentication command.

#define	PHHAL_HW_SAMAV2_CMD_SELECT_APPLICATION_INS 0x5A
	CMD Byte for SAM_SelectApplication command.

#define	PHHAL_HW_SAMAV2_CMD_GET_CHALLENGE_INS 0x84
	CMD Byte for SAM_IsoGetChallenge command.

#define	PHHAL_HW_SAMAV2_CMD_ISO_EXTERNAL_AUTHENTICATE_INS 0x82
	CMD Byte for SAM_IsoExternalAuthenticate command.

#define	PHHAL_HW_SAMAV2_CMD_ISO_INTERNAL_AUTHENTICATE_INS 0x88
	CMD Byte for SAM_IsoInternalAuthenticate command.

#define	PHHAL_HW_SAMAV2_CMD_GET_VERSION_INS 0x60
	CMD Byte for GetVersion command.

#define	PHHAL_HW_SAMAV2_CMD_SLEEP_INS 0x51
	CMD Byte for Sleep command.

Option macros for Sam AV2 Security and Configuration Cmd.SAM_LockUnlock command.
#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_UNLOCK 0x00
	P1 Byte for Unlock.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_LOCK_WO_SPECIFYING_UNLOCK_KEY 0x01
	P1 Byte for Lock command without specifying unlock key.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_LOCK_SPECIFYING_UNLOCK_KEY 0x02
	P1 Byte for Lock command with specifying unlock key.

#define	PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_AV2_MODE_SWITCH 0x03
	P1 Byte for AV2 Mode Switch.

Option macros for Sam AV2 Security and Configuration Cmd.SAM_KillAuthentication command.
#define	PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_DEFAULT 0x00
	Default option mask for SAM_KillAuthentication - kill all valid authentication in the LC.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_PICC_ONLY 0x01
	Option mask for kill only PICC authentication. More...

Detailed Description

SAM commands used for host communication and security related configuration.

Macro Definition Documentation

◆ PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_PICC_ONLY

#define PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_PICC_ONLY 0x01

Option mask for kill only PICC authentication.

Only valid in AV2.

Function Documentation

◆ phhalHw_SamAV2_Cmd_SAM_DisableCrypto()

phStatus_t phhalHw_SamAV2_Cmd_SAM_DisableCrypto	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint16_t	wProMas
	)

Disable cryto-related features of the SAM PERMANENTLY AND IRREVERSIBLY.

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]	wProMas	[In] Two byte mask to specify the desired settings for cryptography-related features.

◆ phhalHw_SamAV2_Cmd_SAM_LockUnlock()

phStatus_t phhalHw_SamAV2_Cmd_SAM_LockUnlock	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bMode,
		uint16_t	wRdKeyNo,
		uint16_t	wRdKeyV,
		uint8_t	bSamKeyNo,
		uint8_t	bSamKeyV,
		uint8_t	bUnlockKeyNo,
		uint8_t	bUnlockKeyV,
		uint32_t	bMaxChainBlocks
	)

Lock or Unlock the SAM.

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]	bMode	[In] One of the below options. PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_UNLOCK PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_LOCK_WO_SPECIFYING_UNLOCK_KEY PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_LOCK_SPECIFYING_UNLOCK_KEY PHHAL_HW_SAMAV2_CMD_LOCK_UNLOCK_P1_AV2_MODE_SWITCH
[in]	wRdKeyNo	[In] Key reference number for readerLib key storage.
[in]	wRdKeyV	[In] Key version for readerLib key storage.
[in]	bSamKeyNo	[In] Key reference number to be used.
[in]	bSamKeyV	[In] Key version to be used.
[in]	bUnlockKeyNo	[In] Unlock Key Number to be used (only used when bMode = 0x01).
[in]	bUnlockKeyV	[In] Unlock Key Version to be used (only used when bMode = 0x01).
[in]	bMaxChainBlocks	[In] Maximal message size under command chaining in MAC or Full Protection (only used during switch from AV1 to AV2).

◆ phhalHw_SamAV2_Cmd_SAM_AuthenticateHost()

phStatus_t phhalHw_SamAV2_Cmd_SAM_AuthenticateHost	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bAuthType_HostMode,
		uint16_t	wRdKeyNo,
		uint16_t	wRdKeyV,
		uint8_t	bSamKeyNo,
		uint8_t	bSamKeyV,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLength
	)

Mutual 2-pass-AV1 or 3-pass-AV2 authentication between Host and SAM.

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]	bAuthType_HostMode	[In] Authentication mode in AV1 or host mode AV2.
[in]	wRdKeyNo	[In] Key reference number for readerLib key storage.
[in]	wRdKeyV	[In] Key version for readerLib key storage.
[in]	bSamKeyNo	[In] Key reference number to be used.
[in]	bSamKeyV	[In] Key version to be used.
[in]	pDivInput	[In] Diversification input data (only used in AV1).
[in]	bDivInputLength	[In] Diversification input data length (only used in AV1).

◆ phhalHw_SamAV2_Cmd_SAM_ActivateOfflineKey()

phStatus_t phhalHw_SamAV2_Cmd_SAM_ActivateOfflineKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bKeyNo,
		uint8_t	bKeyV,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLength
	)

Activation of an OfflineCrypto or an OfflineChange Key.

This command is only available in AV2 mode.

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]	bKeyNo	[In] Key reference number to be used.
[in]	bKeyV	[In] Key version to be used.
[in]	pDivInput	[In] Diversification input data.
[in]	bDivInputLength	[In] Diversification input data length. If set to 00h no diversification is done.

◆ phhalHw_SamAV2_Cmd_SAM_LoadInitVector()

phStatus_t phhalHw_SamAV2_Cmd_SAM_LoadInitVector	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t *	pInitVector,
		uint8_t	bInitVectorLength
	)

Load an Init Vector for the next cryptographic operation into the SAM.

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]	pInitVector	[In] Init Vector.
[in]	bInitVectorLength	[In] Init Vector length.

◆ phhalHw_SamAV2_Cmd_SAM_KillAuthentication()

phStatus_t phhalHw_SamAV2_Cmd_SAM_KillAuthentication	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bOption
	)

Kill all active authentications in this logical channel.

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] Only valid in SamAV2 mode. PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_DEFAULT PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_PICC_ONLY

◆ phhalHw_SamAV2_Cmd_SAM_SelectApplication()

phStatus_t phhalHw_SamAV2_Cmd_SAM_SelectApplication	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t *	pDF_Aid
	)

Select an application by the DF_AID.

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]	pDF_Aid	[In] DESFire application ID. This buffer has to be 3 bytes long.

◆ phhalHw_SamAV2_Cmd_SAM_GetChallenge()

phStatus_t phhalHw_SamAV2_Cmd_SAM_GetChallenge	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bExpL,
		uint8_t *	pRnd
	)

Executes the first part of an ISO compliant authentication procedure (AV1) or fetches a random number from the SAM (AV2).

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]	bExpL	[In] Expected length of data bytes to be retrieved.
[out]	pRnd	[Out] Buffer containing the challenge. It has to be bExpL long.

◆ phhalHw_SamAV2_Cmd_SAM_IsoExternalAuthenticate()

phStatus_t phhalHw_SamAV2_Cmd_SAM_IsoExternalAuthenticate	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bKeyNo,
		uint8_t	bKeyV,
		uint8_t *	pEncRnd,
		uint8_t	bEncRndLength
	)

Executes the second part of an ISO compliant authentication procedure.

Note: This command is only available in AV1 mode.

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]	bKeyNo	[In] Key reference number to be used.
[in]	bKeyV	[In] Key version to be used.
[in]	pEncRnd	[In] Encrypted (Random number PCD1 \|\| Random number PICC1).
[in]	bEncRndLength	[In] Encrypted data length.

◆ phhalHw_SamAV2_Cmd_SAM_IsoInternalAuthenticate()

phStatus_t phhalHw_SamAV2_Cmd_SAM_IsoInternalAuthenticate	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t *	pRPcd2,
		uint8_t	bRPcd2Length,
		uint8_t **	pEncResp,
		uint16_t *	pEncRespLength
	)

Executes the third part of an ISO compliant authentication procedure.

After successfull execution of this command, the Session Key may be generated as described in the SAMAV2 specification.
Note: This command is only available in AV1 mode.

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]	pRPcd2	[In] Random number PCD2.
[in]	bRPcd2Length	[In] Length of RPCD2.
[out]	pEncResp	[Out] Encrypted (Random number PICC2 \|\| Random number PCD2).
[out]	pEncRespLength	[Out] Length of encrypted response.

◆ phhalHw_SamAV2_Cmd_SAM_GetVersion()

phStatus_t phhalHw_SamAV2_Cmd_SAM_GetVersion	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t *	pVersion,
		uint8_t *	pVersionLength
	)

Get version information from the SAM.

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.
[out]	pVersion	[Out] Buffer containing the read version. It has to be 31 bytes long.
[out]	pVersionLength	[Out] Amount of valid bytes in the version buffer.

◆ phhalHw_SamAV2_Cmd_SAM_Sleep()

phStatus_t phhalHw_SamAV2_Cmd_SAM_Sleep ( phhalHw_SamAV2_DataParams_t * pDataParams )

Set the SAM into power down mode.

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.

Macros

Functions

Sam AV2 command code for Sam Security and configuration feature.

Option macros for Sam AV2 Security and Configuration Cmd.SAM_LockUnlock command.

Option macros for Sam AV2 Security and Configuration Cmd.SAM_KillAuthentication command.

Detailed Description

Macro Definition Documentation

◆ PHHAL_HW_SAMAV2_CMD_CHANGE_SAMKILLAUTHENTICATION_PICC_ONLY

Function Documentation

◆ phhalHw_SamAV2_Cmd_SAM_DisableCrypto()

◆ phhalHw_SamAV2_Cmd_SAM_LockUnlock()

◆ phhalHw_SamAV2_Cmd_SAM_AuthenticateHost()

◆ phhalHw_SamAV2_Cmd_SAM_ActivateOfflineKey()

◆ phhalHw_SamAV2_Cmd_SAM_LoadInitVector()

◆ phhalHw_SamAV2_Cmd_SAM_KillAuthentication()

◆ phhalHw_SamAV2_Cmd_SAM_SelectApplication()

◆ phhalHw_SamAV2_Cmd_SAM_GetChallenge()

◆ phhalHw_SamAV2_Cmd_SAM_IsoExternalAuthenticate()

◆ phhalHw_SamAV2_Cmd_SAM_IsoInternalAuthenticate()

◆ phhalHw_SamAV2_Cmd_SAM_GetVersion()

◆ phhalHw_SamAV2_Cmd_SAM_Sleep()