Implementation of SAM Security and Configuration commands. More...

Collaboration diagram for 02_SecurityConfiguration:

Modules
	Defines
	Definitions for SAM Security and Configuration commands.

Functions
phStatus_t	phhalHw_Sam_Cmd_SAM_GetVersion (phhalHw_Sam_DataParams_t pDataParams, uint8_t pVersion, uint8_t *pVerLen)
	Get version information from the SAM. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_DisableCrypto (phhalHw_Sam_DataParams_t *pDataParams, uint16_t wProMas)
	Disable Crypto-related features of the SAM permanently and is irreversible. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_ActivateOfflineKey (phhalHw_Sam_DataParams_t pDataParams, uint8_t bOption, uint8_t bKeyNo, uint8_t bKeyVer, uint8_t pDivInput, uint8_t bDivInputLen)
	Activation of an OfflineCrypto or an OfflineChange Key. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_LoadInitVector (phhalHw_Sam_DataParams_t pDataParams, uint8_t bOption, uint8_t pData, uint8_t bDataLen)
	Load an Init Vector for the next cryptographic operation into the SAM. More...

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

phStatus_t	phhalHw_Sam_Cmd_SAM_SelectApplication (phhalHw_Sam_DataParams_t pDataParams, uint8_t pDF_Aid)
	Select an application by the DF_AID. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_GetRandom (phhalHw_Sam_DataParams_t pDataParams, uint8_t bExpLen, uint8_t pRnd)
	Gets a random number from SAM. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_Sleep (phhalHw_Sam_DataParams_t *pDataParams)
	Set the SAM into power down mode. More...

phStatus_t	phhalHw_Sam_Cmd_SAM_SetConfiguration (phhalHw_Sam_DataParams_t pDataParams, uint8_t bOption, uint8_t pData, uint8_t bDataLen)
	Used to update SAM configuration settings. More...

Detailed Description

Implementation of SAM Security and Configuration commands.

Function Documentation

◆ phhalHw_Sam_Cmd_SAM_GetVersion()

phStatus_t phhalHw_Sam_Cmd_SAM_GetVersion	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t *	pVersion,
		uint8_t *	pVerLen
	)

Get version information from the SAM.

Returns

Bytes[0 - 6]: Hardware version information
- Byte[0] : Vendor ID (set to 0x04 for NXP)
- Byte[1] : Type
- Byte[2] : Subtype
- Byte[3] : Major version number
- Byte[4] : Minor version number
- Byte[5] : Storage size
- Byte[6] : Communication protocol type (set to 0x01, meaning T=1)
Bytes[7 - 13]: Software version information
- Byte[7] : Vendor ID (set to 0x04 for NXP)
- Byte[8] : Type
- Byte[9] : Subtype
- Byte[10] : Major version number
- Byte[11] : Minor version number
- Byte[12] : Storage size
- Byte[13] : Communication protocol type (set to 0x01, meaning T=1)
Bytes[14 - 30]: Manufacturer data
- Byte[14 - 20]: Code the unique serial number
- Byte[11 - 25]: Code the production batch number
- Byte[26] : Code the day of production [0x00..0x1F]
- Byte[27] : Code the month of production [0x00..0x0C]
- Byte[28] : Code the year of production (year is 2000 + code)
- Byte[29] : Global crypto settings; most significant byte of CryptoSecRow
- Byte[30] : Code the SAM version and activated state (set to 0x0X for the unactivated MIFARE SAM AVx, set to 0xAX after SAM Activation). For Ex: 0x04 will be for SAM AV4 Unactivated and 0xA4 will be for SAM AV4 after SAM Activation. For future SAM version the number will increment from lower nibble.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pVersion and pVerLen is NULL.
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.
[out]	pVerLen	[Out] Amount of valid bytes in the pVersion buffer.

◆ phhalHw_Sam_Cmd_SAM_DisableCrypto()

phStatus_t phhalHw_Sam_Cmd_SAM_DisableCrypto	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint16_t	wProMas
	)

Disable Crypto-related features of the SAM permanently and is irreversible.

The SAM shall maintain the status of the cryptographic functionality in the Global Crypto Security Row (CryptoSecRow).
The command shall apply the ProMas bits to the CryptoSecRow and shall not be able to unset the bit (cannot re-enable the functionality).
The initial value of the CryptoSecRow are set to 0x0000, therefore full cryptographic functionality is available.
The configuration settings (SET) of all KST key entries shall reflect the changes after the execution of SAM_DisableCrypto.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
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. No change for programming mask bit Disable DESFire (PICC) key change Disable decryption Disable encryption Disable MAC verification Disable MAC generation

◆ phhalHw_Sam_Cmd_SAM_ActivateOfflineKey()

phStatus_t phhalHw_Sam_Cmd_SAM_ActivateOfflineKey	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t	bKeyNo,
		uint8_t	bKeyVer,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen
	)

Activation of an OfflineCrypto or an OfflineChange Key.

SAM_ActivateOfflineKey shall activate Offline keys for further offline data processing.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pDivInput is 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 if Keytype is AES_128LRP. Generate one updated key Generate two updated keys NO LRP Update, if keytype is other than AES_128LRP.
[in]	bKeyNo	[In] Key reference number in SAM KeyStore.
[in]	bKeyVer	[In] Key version to be used in SAM KeyStore.
[in]	pDivInput	[In] Diversification Input used to diversify the key.
[in]	bDivInputLen	[In] Length bytes available in pDivInput buffer.

◆ phhalHw_Sam_Cmd_SAM_LoadInitVector()

phStatus_t phhalHw_Sam_Cmd_SAM_LoadInitVector	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pData,
		uint8_t	bDataLen
	)

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

SAM_LoadInitVector are used to load an init vector (IV) or encryption counter (LRP_EncCtr) for next cryptographic operations.
The loaded IV will be applied in the next cryptographic operation independent from the Keep IV setting of the key entry, except for the authentication commands where the init vector is reset to zero.
If a KeyType.AES_128LRP key is loaded, the command can also be used to set the LRP_EncCtr used during encryption and decryption.
This is indicated by P1. If the LRP_EncCtr is to be set, a value of up to 16 bytes is given.
Once set, the counter is further maintained and incremented by the SAM.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] One of the below option. Set Initialization Vector Set LRP Encryption Counter
[in]	pData	[In] Data based on the option selected. If Set Initialization Vector, 8 bytes of initialization vector for DES or 16 bytes of initialization vector for AES. If Set LRP Encryption Counter, 1 - 16 bytes Encryption counter.
[in]	bDataLen	[In] The length of bytes available in pData buffer.

◆ phhalHw_Sam_Cmd_SAM_KillAuthentication()

phStatus_t phhalHw_Sam_Cmd_SAM_KillAuthentication	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption
	)

Kill all active authentications in this logical channel.

SAM_KillAuthentication invalidates either any authentication or all but the Host Authentication on the LC on which the command is applied

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] The type of authentication to be killed. Kill any authentication on corresponding LC Kill PICC authentication or Offline Key activation but preserves any Host Authentication

◆ phhalHw_Sam_Cmd_SAM_SelectApplication()

phStatus_t phhalHw_Sam_Cmd_SAM_SelectApplication	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t *	pDF_Aid
	)

Select an application by the DF_AID.

SAM_SelectApplication is the equivalent of the SelectApplication command of DESFire.
The SAM generates a list of available keys linked to the specified Application ID as defined in the key entry property DF_AID.
For every key number, up to 6 key versions can be stored in the list (so it can read the keys from maximum two key entries per DESFire AID and DESFire key number).
This list is filled starting with key entry zero. If the KST contains more than 6 key versions per DESFire AID and DESFire key number, only the first 6 versions will be listed.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	pDF_Aid	[In] DESFire application identifier (3 bytes).

◆ phhalHw_Sam_Cmd_SAM_GetRandom()

phStatus_t phhalHw_Sam_Cmd_SAM_GetRandom	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bExpLen,
		uint8_t *	pRnd
	)

Gets a random number from SAM.

Returns: Status code

Return values

PH_ERR_SUCCESS	Operation successful.
PH_ERR_INVALID_DATA_PARAMS	pDataParams is NULL.
PH_ERR_INVALID_PARAMETER	pRnd is NULL.
PH_ERR_LENGTH_ERROR	If Number of returned bytes are not equal expected number.
Other	Depending on implementation and underlaying component.

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bExpLen	[In] The length of random bytes expected from SAM.
[out]	pRnd	[Out] The random number returned by Sam.

◆ phhalHw_Sam_Cmd_SAM_Sleep()

phStatus_t phhalHw_Sam_Cmd_SAM_Sleep ( phhalHw_Sam_DataParams_t * pDataParams )

Set the SAM into power down mode.

SAM_Sleep will force the SAM to put a connected reader chip into sleep mode and itself into idle mode to reduce power consumption
The SAM will answer the command and afterwards switch to idle mode.
The SAM will automatically return to normal operation after receiving the first character of the next command.
The reader chip will stay in sleep mode until a command is issued which utilizes the reader IC.
Then the SAM automatically carries out the wake-up sequence before starting the requested operation.

Returns: Status code

Return values

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

Parameters

[in] pDataParams [In] Pointer to this layer's parameter structure.

◆ phhalHw_Sam_Cmd_SAM_SetConfiguration()

phStatus_t phhalHw_Sam_Cmd_SAM_SetConfiguration	(	phhalHw_Sam_DataParams_t *	pDataParams,
		uint8_t	bOption,
		uint8_t *	pData,
		uint8_t	bDataLen
	)

Used to update SAM configuration settings.

A successful Host Authentication with one of the three SAM master keys (KeyNo set to 0x00) is required to perform the command

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	bOption	[In] Configuration setting ID. Define length and content of the Data parameter. ATR historical bytes Reader IC configuration I2C processing clock speed Full ATR configuration
[in]	pData	[In] Configuration setting data. If ATR historical bytes, the historical bytes should be exchanged. If Reader IC configuration, one of the below values, RC512 RC523 (Default) RC663 If I2C processing clock speed, one of the below values, 0.5 MHz 1 MHz 2 MHz 3 MHz 4 MHz 6 MHz 8 MHz 12 MHz (Default) 16 MHz Free running mode If Full ATR update
[in]	bDataLen	[In] Length of Configuration setting data.

Modules

Functions

Detailed Description

Function Documentation

◆ phhalHw_Sam_Cmd_SAM_GetVersion()

◆ phhalHw_Sam_Cmd_SAM_DisableCrypto()

◆ phhalHw_Sam_Cmd_SAM_ActivateOfflineKey()

◆ phhalHw_Sam_Cmd_SAM_LoadInitVector()

◆ phhalHw_Sam_Cmd_SAM_KillAuthentication()

◆ phhalHw_Sam_Cmd_SAM_SelectApplication()

◆ phhalHw_Sam_Cmd_SAM_GetRandom()

◆ phhalHw_Sam_Cmd_SAM_Sleep()

◆ phhalHw_Sam_Cmd_SAM_SetConfiguration()