SAM commands used for key management related configuration. More...

Collaboration diagram for Key Management:

Macros
#define	PHHAL_HW_SAMAV2_CMD_AV1_KEY_ENTRY_RESPONSE_NO_VC_LENGTH 0x0BU
	Response in AV1 Mode length if VC is not available.

#define	PHHAL_HW_SAMAV2_CMD_AV1_KEY_ENTRY_RESPONSE_VC_LENGTH 0x0CU
	Response in AV1 Mode length if VC is available.

#define	PHHAL_HW_SAMAV2_CMD_AV2_KEY_ENTRY_RESPONSE_NO_VC_LENGTH 0x0CU
	Response in AV2 Mode length if VC is not available.

#define	PHHAL_HW_SAMAV2_CMD_AV2_KEY_ENTRY_RESPONSE_VC_LENGTH 0x0DU
	Response in AV2 Mode length if VC is available.

Functions
phStatus_t	phhalHw_SamAV2_Cmd_SAM_ChangeKeyEntry (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bOption, uint8_t bKeyNo, uint8_t bProMas, uint8_t pKeyData, uint8_t bKeyDataLength)
	Change a symmetric key entry in the key table of the SAM. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_GetKeyEntry (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bKeyNo, uint8_t pKeyEntry, uint8_t *bKeyEntryLength)
	Get information about a key entry. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_ChangeKUCEntry (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bOption, uint8_t bKucNo, uint8_t bProMas, uint8_t pKucData, uint8_t KucDataLength)
	Change the key usage counter (KUC). More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_GetKUCEntry (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bKucNo, uint8_t pKucEntry)
	Get information about a key usage counter (KUC). More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_DumpSecretKey (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bCrypto, uint8_t bKeyNo, uint8_t bKeyV, uint8_t pDivInput, uint8_t bDivInputLength, uint8_t pSecretKey, uint8_t pSecretKeyLength)
	Retrive a PICC key stored in the key table. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_DumpSessionKey (phhalHw_SamAV2_DataParams_t pDataParams, phhalHw_SamAV2_DataParams_t pDataParamsEnc, uint8_t bCrypto, uint8_t pSessionKey, uint8_t pSessionKeyLength)
	Dump the current session key. More...

phStatus_t	phhalHw_SamAV2_Cmd_SAM_DisableKeyEntry (phhalHw_SamAV2_DataParams_t pDataParams, uint8_t bKeyNo, uint8_t pOfflineCryptogram, uint8_t bCryptogramLength)
	Disable a key entry. More...

Sam AV2 command code for Sam Key Management feature.
#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_INS 0xC1U
	CMD Byte for ChangeKeyEntry command.

#define	PHHAL_HW_SAMAV2_CMD_GET_KEYENTRY_INS 0x64U
	CMD Byte for GetKeyEntry command.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_INS 0xCCU
	CMD Byte for ChangeKUCEntry command.

#define	PHHAL_HW_SAMAV2_CMD_GET_KUCENTRY_INS 0x6CU
	CMD Byte for GetKUCEntry command.

#define	PHHAL_HW_SAMAV2_CMD_DUMP_SESSIONKEY_INS 0xD5U
	CMD Byte for DumpSessionKey command.

#define	PHHAL_HW_SAMAV2_CMD_DUMP_SECRETKEY_INS 0xD6U
	CMD Byte for DumpSecretKey command.

#define	PHHAL_HW_SAMAV2_CMD_DISABLE_KEYENTRY_INS 0xD8U
	CMD Byte for DisableKeyEntry command.

Option macros for Sam AV2 KeyManagement Cmd.SAM_ChangeKeyEntry command.
#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_DEFAULT 0x00
	Default option mask for ChangeKeyEntry.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_PLAIN 0x01
	Option mask for a plain ChangeKeyEntry in AV1.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_ENCRYPTED 0x00
	Option mask for a encrypted ChangeKeyEntry in AV1.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEYA_MASK 0x80U
	Option to set KeyA update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEYB_MASK 0x40U
	Option to set KeyB update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEYC_MASK 0x20U
	Option to set KeyB update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_DFAID_MASK 0x10U
	Option to set DFAID update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEYCEK_MASK 0x08U
	Option to set KeyNoCEK and KeyVCEK update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_REFNOKUC_MASK 0x04U
	Option to set RefNoLUC update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_SET_MASK 0x02U
	Option to set SET update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_SENT_KEY_VERSIONS_MASK 0x01U
	Option to set ExtSET update in programming mask bit.

Option macros for Sam AV2 KeyManagement Cmd.SAM_ChangeKUCEntry command.
#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_DEFAULT 0x00
	Default option mask for ChangeKUCEntry.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_PLAIN 0x01
	Option mask for a plain ChangeKUCEntry in AV1.

#define	PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_ENCRYPTED 0x00
	Option mask for a encrypted ChangeKUCEntry in AV1.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_LIMIT_MASK 0x80U
	Option to set Limit update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEYNO_CKUC_MASK 0x40U
	Option to set KeyNoCKUC update in programming mask bit.

#define	PHHAL_HW_SAMAV2_CMD_UPDATE_KEY_VCKUC_MASK 0x20U
	Option to set KeyVCKUC update in programming mask bit.

Detailed Description

SAM commands used for key management related configuration.

Function Documentation

◆ phhalHw_SamAV2_Cmd_SAM_ChangeKeyEntry()

phStatus_t phhalHw_SamAV2_Cmd_SAM_ChangeKeyEntry	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bKeyNo,
		uint8_t	bProMas,
		uint8_t *	pKeyData,
		uint8_t	bKeyDataLength
	)

Change a symmetric key entry in the key table of 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]	bOption	[In] Option mask for this command - only used in AV1. PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_DEFAULT PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_PLAIN PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_ENCRYPTED
[in]	bKeyNo	[In] Reference number of the key entry to be changed (00h to 7Fh).
[in]	bProMas	[In] Program mask indicating the fields that should be changed. PHHAL_HW_SAMAV2_CMD_UPDATE_KEYA_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_KEYB_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_KEYB_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_DFAID_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_KEYCEK_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_REFNOKUC_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_SET_MASK PHHAL_HW_SAMAV2_CMD_SENT_KEY_VERSIONS_MASK
[in]	pKeyData	[In] Buffer containing the key data: AV1 and host authentication with session key: key data = (plain key entry); Flag PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_PLAIN in option byte has to be cleared. AV1 and host authentication with secret key: key data = (plain key entry \| UID \| CRC \| padding) encrypted with secret key; option byte is not used. AV1 and KeyNoCEK is set to FEh: key data = (plain key entry \| UID); Flag PHHAL_HW_SAMAV2_CMD_CHANGE_KEYENTRY_PLAIN in option byte has to be set. AV2 and host authentication: key data = (plain key entry). AV2 and offline key activation: key data = (offline key data). AV2 and KeyNoCEK is set to FEh: key data = (plain key entry).
[in]	bKeyDataLength	[In] Length of the key data buffer.

◆ phhalHw_SamAV2_Cmd_SAM_GetKeyEntry()

phStatus_t phhalHw_SamAV2_Cmd_SAM_GetKeyEntry	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bKeyNo,
		uint8_t *	pKeyEntry,
		uint8_t *	bKeyEntryLength
	)

Get information about a key entry.

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] Reference number of the key entry to be returned (00h to 7Fh).
[out]	pKeyEntry	[Out] Buffer containing the information about the key entry. This buffer has to be 13 bytes long.
[out]	bKeyEntryLength	[Out] Amount of valid bytes in pKeyEntry.

◆ phhalHw_SamAV2_Cmd_SAM_ChangeKUCEntry()

phStatus_t phhalHw_SamAV2_Cmd_SAM_ChangeKUCEntry	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bKucNo,
		uint8_t	bProMas,
		uint8_t *	pKucData,
		uint8_t	KucDataLength
	)

Change the key usage counter (KUC).

Selection is done by its reference number.

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] Option mask for this command - only used in AV1. PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_DEFAULT PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_PLAIN PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_ENCRYPTED
[in]	bKucNo	[In] Reference number of the key usage counter to be updated (00h to 0Fh).
[in]	bProMas	[In] Program mask indicating the fields that should be changed. PHHAL_HW_SAMAV2_CMD_UPDATE_LIMIT_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_KEYNO_CKUC_MASK PHHAL_HW_SAMAV2_CMD_UPDATE_KEY_VCKUC_MASK
[in]	pKucData	[In] Buffer containing the KUC data: AV1 and host authentication with session key: KUC data = (plain KUC entry); Flag PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_PLAIN in option byte has to be cleared. AV1 and host authentication with secret key: KUC data = (plain KUC entry \| UID \| CRC \| padding) encrypted with secret key; bSkipEncryption is not used. AV1 and KeyNoCKUC is set to FEh: KUC data = (plain KUC entry \| UID); Flag PHHAL_HW_SAMAV2_CMD_CHANGE_KUCENTRY_PLAIN in option byte has to be set. AV2 and host authentication: KUC data = (plain KUC entry). AV2 and offline key activation: KUC data = (offline KUC data). AV2 and KeyNoCKUC is set to FEh: KUC data = (plain KUC entry).
[in]	KucDataLength	[In] Length of the KUC data.

◆ phhalHw_SamAV2_Cmd_SAM_GetKUCEntry()

phStatus_t phhalHw_SamAV2_Cmd_SAM_GetKUCEntry	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bKucNo,
		uint8_t *	pKucEntry
	)

Get information about a key usage counter (KUC).

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]	bKucNo	[In] Reference number of the key usage counter to be returned (00h to 0Fh).
[out]	pKucEntry	[Out] Buffer containing the KUC entry. This buffer has to be 10 bytes long.

◆ phhalHw_SamAV2_Cmd_SAM_DumpSecretKey()

phStatus_t phhalHw_SamAV2_Cmd_SAM_DumpSecretKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bCrypto,
		uint8_t	bKeyNo,
		uint8_t	bKeyV,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLength,
		uint8_t *	pSecretKey,
		uint8_t *	pSecretKeyLength
	)

Retrive a PICC key stored in the key table.

This command is only available in AV2.

The pSecretKey buffer contains always the plain session key even if bUseCrypto is set.

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]	bCrypto	[In] Bit mask containing the crypto options for the key dump.
[in]	bKeyNo	[In] Reference number of the key entry to be dumped.
[in]	bKeyV	[In] Reference number of the key entry to be dumped.
[in]	pDivInput	[In] Diversification input data.
[in]	bDivInputLength	[In] Diversification input data length. If set to 00h no diversification is used.
[out]	pSecretKey	[Out] Buffer containing the plain secret key. It has to be 24 bytes long.
[out]	pSecretKeyLength	[Out] Amount of valid bytes in secret key buffer.

◆ phhalHw_SamAV2_Cmd_SAM_DumpSessionKey()

phStatus_t phhalHw_SamAV2_Cmd_SAM_DumpSessionKey	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		phhalHw_SamAV2_DataParams_t *	pDataParamsEnc,
		uint8_t	bCrypto,
		uint8_t *	pSessionKey,
		uint8_t *	pSessionKeyLength
	)

Dump the current session key.

In AV2 the pSessionKey buffer contains always the plain session key.

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]	pDataParamsEnc	[In] Pointer to the layer's parameter structure whose session key shall be used for response encryption. Only used in AV1 whenever encryption is selected.
[in]	bCrypto	[In] Crypto settings. AV1: bit 0 indicates if the key shall be encrypted or not. AV1: bit 1-2 indicates the LC number whose current session key shall be used for encryption. AV2: bit 0 indicates if the key shall be encrypted under MAC protection.
[out]	pSessionKey	[Out] Buffer containig the session key. It has to be 24 bytes long.
[out]	pSessionKeyLength	[Out] Amount of valid bytes in session key buffer.

◆ phhalHw_SamAV2_Cmd_SAM_DisableKeyEntry()

phStatus_t phhalHw_SamAV2_Cmd_SAM_DisableKeyEntry	(	phhalHw_SamAV2_DataParams_t *	pDataParams,
		uint8_t	bKeyNo,
		uint8_t *	pOfflineCryptogram,
		uint8_t	bCryptogramLength
	)

Disable a key entry.

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] Number of the key entry to be disabled (00h to 7Fh).
[out]	pOfflineCryptogram	[Out] Buffer containing the cryptogram for offline key deactivation. This parameter is only used in AV2.
[out]	bCryptogramLength	[Out] Length of the offline cryptogram. If set to 00h no offline cryptogram is sent.

Macros

Functions

Sam AV2 command code for Sam Key Management feature.

Option macros for Sam AV2 KeyManagement Cmd.SAM_ChangeKeyEntry command.

Option macros for Sam AV2 KeyManagement Cmd.SAM_ChangeKUCEntry command.

Detailed Description

Function Documentation

◆ phhalHw_SamAV2_Cmd_SAM_ChangeKeyEntry()

◆ phhalHw_SamAV2_Cmd_SAM_GetKeyEntry()

◆ phhalHw_SamAV2_Cmd_SAM_ChangeKUCEntry()

◆ phhalHw_SamAV2_Cmd_SAM_GetKUCEntry()

◆ phhalHw_SamAV2_Cmd_SAM_DumpSecretKey()

◆ phhalHw_SamAV2_Cmd_SAM_DumpSessionKey()

◆ phhalHw_SamAV2_Cmd_SAM_DisableKeyEntry()