Component : SAM (AV4 and future SAM's)

KeyStore component implementation for SAM (AV4 and future SAM's). More...

Collaboration diagram for Component : SAM (AV4 and future SAM's):

Modules
	Define
	Definitions for SAM (AV4 and future SAM's) KeyStore component.

Data Structures
struct	phKeyStore_Sam_DataParams_t
	SAM (AV4 and future SAM's) parameter structure. More...
struct	phKeyStore_Sam_KeyEntry_t
	Data structure for KeyStore SAM (AV4 and future SAM's) layer implementation. More...

Functions
phStatus_t	phKeyStore_Sam_Init (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wSizeOfDataParams, phhalHw_Sam_DataParams_t *pHalDataParams)
	Initializes the KeyStore component as SAM (AV4 and future SAM's) component. More...
phStatus_t	phKeyStore_Sam_FormatKeyEntry (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t wKeyType)
	Format a key entry to a new KeyType. More...
phStatus_t	phKeyStore_Sam_SetKUC (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t wRefNoKUC)
	Change the KUC of a key entry. More...
phStatus_t	phKeyStore_Sam_GetKUC (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wRefNoKUC, uint32_t *pdwLimit, uint32_t *pdwCurVal)
	Obtain a key usage counter entry. More...
phStatus_t	phKeyStore_Sam_ChangeKUC (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wRefNoKUC, uint32_t dwLimit)
	Change a key usage counter entry. More...
phStatus_t	phKeyStore_Sam_SetConfig (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wConfig, uint16_t wValue)
	Set configuration parameter. More...
phStatus_t	phKeyStore_Sam_SetConfigStr (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wConfig, uint8_t *pBuffer, uint16_t wBufferLen)
	Set the DESFire Application Identifier. More...
phStatus_t	phKeyStore_Sam_GetConfig (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wConfig, uint16_t *pValue)
	Get configuration parameter. More...
phStatus_t	phKeyStore_Sam_GetConfigStr (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wConfig, uint8_t **ppBuffer, uint16_t *pBufferLen)
	Get the DESFire Application Identifier. More...
phStatus_t	phKeyStore_Sam_SetKey (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t wKeyVer, uint16_t wKeyType, uint8_t *pNewKey, uint16_t wNewKeyVer)
	Change a key entry at a given version. More...
phStatus_t	phKeyStore_Sam_SetKeyAtPos (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t wPos, uint16_t wKeyType, uint8_t *pKey, uint16_t wKeyVer)
	Change a key entry at the specified position. More...
phStatus_t	phKeyStore_Sam_SetFullKeyEntry (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wNoOfKeys, uint16_t wKeyNo, uint16_t wNewRefNoKUC, uint16_t wNewKeyType, uint8_t *pNewKeys, uint16_t *pNewKeyVerList)
	Change a full key entry. More...
phStatus_t	phKeyStore_Sam_GetKey (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t wKeyVer, uint8_t bKeyBufSize, uint8_t *pKey, uint16_t *pKeyType)
	Get a key. More...
phStatus_t	phKeyStore_Sam_GetKeyEntry (phKeyStore_Sam_DataParams_t *pDataParams, uint16_t wKeyNo, uint16_t *pKeyVer, uint16_t *pKeyVerLen, uint16_t *pKeyType)
	Get a key entry information block. More...

Detailed Description

KeyStore component implementation for SAM (AV4 and future SAM's).

• Supports loading and retrieval of Symmetric Key information from SAM's NVM (Non-Volatile Memory) and RAM (Random Access Memory) KeyStore.
• MIFARE Key Type is not supported.
• AES128 LRP (Leakage Resilient Primitive) Key Type is supported.

Function Documentation

phKeyStore_Sam_Init()

phStatus_t phKeyStore_Sam_Init	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wSizeOfDataParams,
		phhalHw_Sam_DataParams_t *	pHalDataParams
	)

Initializes the KeyStore component as SAM (AV4 and future SAM's) component.

Returns

Status code

Return values

PH_ERR_SUCCESS

Operation successful.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wSizeOfDataParams	[In] Specifies the size of the data parameter structure.
[in]	pHalDataParams	[In] Pointer to the parameter structure of the underlying layer.

phKeyStore_Sam_FormatKeyEntry()

phStatus_t phKeyStore_Sam_FormatKeyEntry	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t	wKeyType
	)

Format a key entry to a new KeyType.

• The function changes a symmetric key entry of the SAM to a new key type. First the command SAM_GetKeyEntry is executed to get the current change key number of the key entry.
• Afterwards a new key entry is written by the SAM_ChangeKeyEntry command.
• The keys and key versions, of this new entry are set to zero.
• DF_Aid, DFKeyNo, RefNoKUC, SET, ExtSET, KeyNoCEK, KeyVCEK, KeyNoAEK and KeyVAEK are set according to the configuration parameters.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] KeyEntry number to be formatted. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[in]	wKeyType	[In] New key type of the KeyEntry (predefined type of KeyType). One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]

phKeyStore_Sam_SetKUC()

phStatus_t phKeyStore_Sam_SetKUC	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t	wRefNoKUC
	)

Change the KUC of a key entry.

• First the command SAM_GetKeyEntry is executed to get the change key of the current key entry.
• Afterwards the reference number of the KUC is set to wRefNoKUC via the SAM_ChangeKeyEntry command.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] Key number of the key to be loaded. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[in]	wRefNoKUC	[In] Reference Number of the key usage counter used together with that key.

phKeyStore_Sam_GetKUC()

phStatus_t phKeyStore_Sam_GetKUC	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wRefNoKUC,
		uint32_t *	pdwLimit,
		uint32_t *	pdwCurVal
	)

Obtain a key usage counter entry.

The function returns the KUC entry retrieved by the SAM_GetKUCEntry command. KeyNoCKUC and KeyVCKUC are stored in the configuration parameters and can be accessed via the GetConfig function.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wRefNoKUC	[In] Number of the key usage counter to be looked at (00h to 0Fh)
[out]	pdwLimit	[Out] Currently set Limit in the KUC.
[out]	pdwCurVal	[Out] Currently value in the KUC.

phKeyStore_Sam_ChangeKUC()

phStatus_t phKeyStore_Sam_ChangeKUC	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wRefNoKUC,
		uint32_t	dwLimit
	)

Change a key usage counter entry.

The function changes the KUC by using the SAM_ChangeKUCEntry command. KeyNoCKUC and KeyVCKUC are set to according to the configuration parameters.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wRefNoKUC	[In] Number of the key usage counter.
[in]	dwLimit	[In] Limit of the Key Usage Counter.

phKeyStore_Sam_SetConfig()

phStatus_t phKeyStore_Sam_SetConfig	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wConfig,
		uint16_t	wValue
	)

Set configuration parameter.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wConfig is having a identifier that is not supported.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wConfig	[In] Configuration Identifier
[in]	wValue	[In] Configuration Value

phKeyStore_Sam_SetConfigStr()

phStatus_t phKeyStore_Sam_SetConfigStr	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wConfig,
		uint8_t *	pBuffer,
		uint16_t	wBufferLen
	)

Set the DESFire Application Identifier.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wConfig is having a identifier that is not supported.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wConfig	[In] Configuration Identifier, mainly DF_AID is supported.
[in]	pBuffer	[In] Buffer containing the DESFire Application Identifier.
[in]	wBufferLen	[In] Length of data available in pBuffer.

phKeyStore_Sam_GetConfig()

phStatus_t phKeyStore_Sam_GetConfig	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wConfig,
		uint16_t *	pValue
	)

Get configuration parameter.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wConfig is having a identifier that is not supported.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wConfig	[In] Configuration Identifier
[out]	pValue	[Out] Configuration Value

phKeyStore_Sam_GetConfigStr()

phStatus_t phKeyStore_Sam_GetConfigStr	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wConfig,
		uint8_t **	ppBuffer,
		uint16_t *	pBufferLen
	)

Get the DESFire Application Identifier.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wConfig is having a identifier that is not supported.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wConfig	[In] Configuration Identifier, mainly DF_AID is supported.
[out]	ppBuffer	[Out] Buffer containing the DESFire Application Identifier.
[out]	pBufferLen	[Out] Length of data available in pBuffer.

phKeyStore_Sam_SetKey()

phStatus_t phKeyStore_Sam_SetKey	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t	wKeyVer,
		uint16_t	wKeyType,
		uint8_t *	pNewKey,
		uint16_t	wNewKeyVer
	)

Change a key entry at a given version.

• First the command SAM_GetKeyEntry is executed to get the information about the current key entry.
• If the current key type does not match with wKeyType or if the selected key version wKeyVer is not part of the current key entry the function is aborted.
• Otherwise the key with the given version is set to pKey and its version is set to wNewKeyVer by the SAM_ChangeKeyEntry.
• DF_Aid, DFKeyNo, RefNoKUC, SET, ExtSET, KeyNoCEK, KeyVCEK, KeyNoAEK and KeyVAEK are set according to the configuration parameters.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] Key number of the key to be loaded. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[in]	wKeyVer	[In] Key version of the key to be loaded.
[in]	wKeyType	[In] New key type of the KeyEntry (predefined type of KeyType). One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]
[in]	pNewKey	[In] The key information to be updated.
[in]	wNewKeyVer	[In] New Key version of the key to be updated.

phKeyStore_Sam_SetKeyAtPos()

phStatus_t phKeyStore_Sam_SetKeyAtPos	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t	wPos,
		uint16_t	wKeyType,
		uint8_t *	pKey,
		uint16_t	wKeyVer
	)

Change a key entry at the specified position.

• First the command SAM_GetKeyEntry is executed to get the information about the current key entry.
  • If the current key type does not match with wKeyType or if the selected key position is wrong the function is aborted.
  • Otherwise the key at position wPos (00h to 02h) is set to pKey and its version is set to wKeyVer by the SAM_GetKeyEntry.
  • DF_Aid, DFKeyNo, RefNoKUC, SET, ExtSET, KeyNoCEK, KeyVCEK, KeyNoAEK and KeyVAEK are set according to the configuration parameters.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
-	KeyType mismatch or wrong wPos.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] Key number of the key to be loaded. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[in]	wPos	[In] Key position to be updated.
[in]	wKeyType	[In] New key type of the KeyEntry (predefined type of KeyType). One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]
[in]	pKey	[In] The key information to be loaded.
[in]	wKeyVer	[In] Key version of the key to be updated.

phKeyStore_Sam_SetFullKeyEntry()

phStatus_t phKeyStore_Sam_SetFullKeyEntry	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wNoOfKeys,
		uint16_t	wKeyNo,
		uint16_t	wNewRefNoKUC,
		uint16_t	wNewKeyType,
		uint8_t *	pNewKeys,
		uint16_t *	pNewKeyVerList
	)

Change a full key entry.

• First the command SAM_GetKeyEntry is executed to get the information about the current key entry.
• If the current key type does not match with wKeyType also all keys of the entry have to be updated.
• If wNoOfKeys is 01h key A is changed to pKeys, if it is 02h key A and B are changed to pKeys and if it is 03h key A, B and C are changed to pKeys via the SAM_ChangeKeyEntry command.
• If a key is changed also its version is changed to the value listed in pKeyVerList. Keys which are not provided by pKeys are set to zero together with its versions.
• If wNoOfKeys is set to 0 key and version update is skipped.
• The fields DF_Aid, DFKeyNo, SET, ExtSET, KeyNoCEK, KeyVCEK, KeyNoAEK and KeyVAEK are set according to the configuration parameters.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wNoOfKeys	[In] Number of keys in pNewKeys.
[in]	wKeyNo	[In] Number of the keys to be changed in the entry.
[in]	wNewRefNoKUC	[In] Reference number of the key usage counter to be used.
[in]	wNewKeyType	[In] Key type of the new key. One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]
[in]	pNewKeys	[In] Buffer containing the Keys to be updated. This buffer has to be wNoOfKeys * Key Length bytes long.
[in]	pNewKeyVerList	[In] KeyVersionList of the key to be loaded. This buffer has to be wNoOfKeys * 2 bytes long.

phKeyStore_Sam_GetKey()

phStatus_t phKeyStore_Sam_GetKey	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t	wKeyVer,
		uint8_t	bKeyBufSize,
		uint8_t *	pKey,
		uint16_t *	pKeyType
	)

Get a key.

The function returns a key selected by its key version:

• The command is not supported in AV1
• To retrieve a key in AV3 a SAM_DumpSecretKey is executed. Therefore the flag 'Allow dump secret key' in ExtSet of the key entry has to be enabled. If a DES key is dumped, the key version is encoded into every least significant bit of the first 8 key bytes.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] Key number of the key to be retrieved. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[in]	wKeyVer	[In] Key version of the key to be retrieved.
[in]	bKeyBufSize	[In] Size of the key buffer.
[out]	pKey	[Out] Pointer to the key itself.
[out]	pKeyType	[Out] Type of the key. One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]

phKeyStore_Sam_GetKeyEntry()

phStatus_t phKeyStore_Sam_GetKeyEntry	(	phKeyStore_Sam_DataParams_t *	pDataParams,
		uint16_t	wKeyNo,
		uint16_t *	pKeyVer,
		uint16_t *	pKeyVerLen,
		uint16_t *	pKeyType
	)

Get a key entry information block.

• The function returns the key type and all key versions of a key entry.
• This information is retrieved by the SAM_GetKeyEntrycommand.
• All additional information which is returned by the SAM_GetKeyEntry command is stored in the configuration parameters of this layer.
• To access these values the function GetConfig has to be used.

Returns

Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_PARAMETER	If wKeyNo = INVALID value.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layers parameter structure.
[in]	wKeyNo	[In] Key number of the key entry of interest. One of the following, NVM Keys: 0x00 - 0x7F RAM Keys: 0xE0 - 0xE3
[out]	pKeyVer	[Out] Array for version information.
[out]	pKeyVerLen	[Out] Length of bytes available in pKeyVer buffer.
[out]	pKeyType	[Out] Type of the key. One of the following. AES128 AES192 AES256 DES Single Key [8 Bytes] 2 Key Triple Des [16 Bytes] 3 Key Triple Des [24 Bytes]