These Components implement the Virtual Card Architecture (R) commands for Virtual Card feature. More...

Collaboration diagram for Virtual Card commands:

Functions
phStatus_t	phalVca_IsoSelect (void pDataParams, uint8_t bSelectionControl, uint8_t bOption, uint8_t bDFnameLen, uint8_t pDFname, uint8_t pDivInput, uint8_t bDivInputLen, uint8_t bEncKeyNo, uint8_t bEncKeyVer, uint8_t bMacKeyNo, uint8_t bMacKeyVer, uint8_t pResponse, uint16_t *pRespLen)
	PCD explicitly indicates which Virtual Card it wants to target by issuing this command. More...

phStatus_t	phalVca_IsoExternalAuthenticate (void pDataParams, uint8_t pInData, uint16_t wKeyNumber, uint16_t wKeyVersion)
	Depending on the VC configuration, the PCD might be required to subsequently (after IsoSelect execution) authenticate itself via this command before the targeted VC becomes selected. More...

Custom Error Codes
phStatus_t	phalVca_StartCardSelection (void *pDataParams)
	Start Card Selection. More...

phStatus_t	phalVca_FinalizeCardSelection (void pDataParams, uint16_t pNumValidIids)
	Finalize Card Selection. More...

phStatus_t	phalVca_SelectVc (void *pDataParams, uint16_t wValidIidIndex, uint16_t wKeyNumber, uint16_t wKeyVersion)
	Performs a Select Virtual Card command (MIFARE Plus only). More...

phStatus_t	phalVca_DeselectVc (void *pDataParams)
	Performs a Deselect Virtual Card command. More...

phStatus_t	phalVca_VcSupport (void pDataParams, uint8_t pIid, uint16_t wKeyEncNumber, uint16_t wKeyEncVersion, uint16_t wKeyMacNumber, uint16_t wKeyMacVersion)
	Performs a Virtual Card Support command (MIFARE Plus only). More...

phStatus_t	phalVca_VcSupportLast (void pDataParams, uint8_t pIid, uint8_t bLenCap, uint8_t *pPcdCapabilities, uint16_t wKeyEncNumber, uint16_t wKeyEncVersion, uint16_t wKeyMacNumber, uint16_t wKeyMacVersion)
	Perform a Virtual Card Support (Last) command. More...

phStatus_t	phalVca_GetIidInfo (void pDataParams, uint16_t wValidIidIndex, uint16_t pIidIndex, uint8_t pVcUidSize, uint8_t pVcUid, uint8_t pInfo, uint8_t pPdCapabilities)
	Retrieve card information. More...

Option to be used for ISOSelect command when called for SAM X or S configuration.
#define	PHAL_VCA_ISO_SELECT_SELECTION_DF_NAME 0x04
	Option mask to indicate the selection control as DFName.

#define	PHAL_VCA_ISO_SELECT_FCI_RETURNED 0x00
	Option mask to indicate the return of FCI information.

#define	PHAL_VCA_ISO_SELECT_VARIANT_PART1 0x00
	Option mask for complete VC selection in 1 part.

#define	PHAL_VCA_ISO_SELECT_VARIANT_PART2 0x08
	Option mask for complete VC selection in 2 part.

#define	PHAL_VCA_ISO_SELECT_DIV_DISABLED 0x00
	Default option mask to disable the diversification of VcSelect MAC or ENC key.

#define	PHAL_VCA_ISO_SELECT_ENC_KEY_DIV_INPUT 0x01
	Option mask to perform diversification of VC SelectENC key using the diversification input provided.

#define	PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_INPUT 0x02
	Option mask to perform diversification of VC SelectMAC key using the diversification input provided.

#define	PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_VCUID 0x04
	Option mask to perform diversification of VC SelectMAC key using Virtual Card Identifier.

#define	PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_INPUT_VCUID 0x06
	Option mask to perform diversification of VC SelectMAC key using Virtual Card Identifier and Diversification input provided.

Detailed Description

These Components implement the Virtual Card Architecture (R) commands for Virtual Card feature.

Function Documentation

◆ phalVca_StartCardSelection()

phStatus_t phalVca_StartCardSelection ( void * pDataParams )

Start Card Selection.

This command is used to start a VCS / VCSL sequence.

Returns: Status code

Return values

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

Parameters

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

◆ phalVca_FinalizeCardSelection()

phStatus_t phalVca_FinalizeCardSelection	(	void *	pDataParams,
		uint16_t *	pNumValidIids
	)

Finalize Card Selection.

This command is used to finalize a VCS/VCSL sequence. The number of sucessfully detected IIDs is returned

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[out]	pNumValidIids	[Out] Number of valid IIDs detected during VCS/VCSL sequence execution.

◆ phalVca_SelectVc()

phStatus_t phalVca_SelectVc	(	void *	pDataParams,
		uint16_t	wValidIidIndex,
		uint16_t	wKeyNumber,
		uint16_t	wKeyVersion
	)

Performs a Select Virtual Card command (MIFARE Plus only).

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wValidIidIndex	[In] Index of valid IID, needs to be < pNumValidIids in FinalizeCardSelection call.
[in]	wKeyNumber	[In] Key number of the MAC key used in SVC command.
[in]	wKeyVersion	[In] Key version of the MAC key used in SVC command.

◆ phalVca_DeselectVc()

phStatus_t phalVca_DeselectVc ( void * pDataParams )

Performs a Deselect Virtual Card command.

Returns: Status code

Return values

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

Parameters

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

◆ phalVca_VcSupport()

phStatus_t phalVca_VcSupport	(	void *	pDataParams,
		uint8_t *	pIid,
		uint16_t	wKeyEncNumber,
		uint16_t	wKeyEncVersion,
		uint16_t	wKeyMacNumber,
		uint16_t	wKeyMacVersion
	)

Performs a Virtual Card Support command (MIFARE Plus only).

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	pIid	[In] Installation Identifier (16 bytes).
[in]	wKeyEncNumber	[In] Key number of the ENC key associated to the Iid.
[in]	wKeyEncVersion	[In] Key version of the ENC key associated to the Iid.
[in]	wKeyMacNumber	[In] Key number of the MAC key associated to the Iid.
[in]	wKeyMacVersion	[In] Key version of the MAC key associated to the Iid.

◆ phalVca_VcSupportLast()

phStatus_t phalVca_VcSupportLast	(	void *	pDataParams,
		uint8_t *	pIid,
		uint8_t	bLenCap,
		uint8_t *	pPcdCapabilities,
		uint16_t	wKeyEncNumber,
		uint16_t	wKeyEncVersion,
		uint16_t	wKeyMacNumber,
		uint16_t	wKeyMacVersion
	)

Perform a Virtual Card Support (Last) command.

This command performs the Virtual card support command in ISO14443 Layer 3 activated state. This comand is supported by MIFARE Ultralight EV1 and Mifare Plus product only.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	pIid	[In] Installation Identifier (16 bytes).
[in]	bLenCap	[In] Length of the PCDcaps (0-6).
[in]	pPcdCapabilities	[In] PCD Capabilities (bLenCap bytes), ignored if bLenCap == 0.
[in]	wKeyEncNumber	[In] Key number of the ENC key used in VCSL command.
[in]	wKeyEncVersion	[In] Key version of the ENC key used in VCSL command.
[in]	wKeyMacNumber	[In] Key number of the MAC key used in VCSL command.
[in]	wKeyMacVersion	[In] Key version of the MAC key used in VCSL command.

◆ phalVca_GetIidInfo()

phStatus_t phalVca_GetIidInfo	(	void *	pDataParams,
		uint16_t	wValidIidIndex,
		uint16_t *	pIidIndex,
		uint8_t *	pVcUidSize,
		uint8_t *	pVcUid,
		uint8_t *	pInfo,
		uint8_t *	pPdCapabilities
	)

Retrieve card information.

This command retrieves card information like UID and Info byte and the associated IID

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure.
[in]	wValidIidIndex	[In] Index of valid IID, needs to be < pNumValidIids in FinalizeCardSelection call.
[out]	pIidIndex	[Out] Corresponding IID to the key pair where the MAC was matching in VCSL command call.
[out]	pVcUidSize	[Out] Size of the VC UID (4 or 7 bytes).
[out]	pVcUid	[Out] VC UID (pVcUidSize bytes).
[out]	pInfo	[Out] Info byte.
[out]	pPdCapabilities	[Out] PD Capabilities (2 bytes).

◆ phalVca_IsoSelect()

phStatus_t phalVca_IsoSelect	(	void *	pDataParams,
		uint8_t	bSelectionControl,
		uint8_t	bOption,
		uint8_t	bDFnameLen,
		uint8_t *	pDFname,
		uint8_t *	pDivInput,
		uint8_t	bDivInputLen,
		uint8_t	bEncKeyNo,
		uint8_t	bEncKeyVer,
		uint8_t	bMacKeyNo,
		uint8_t	bMacKeyVer,
		uint8_t *	pResponse,
		uint16_t *	pRespLen
	)

PCD explicitly indicates which Virtual Card it wants to target by issuing this command.

Both PCD and the PD agree on which VC to use (if any) and they negotiate the capabilities that they will use. This command is supported by DESFire EV1, DESFire EV2 and Plus EV1 only.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure which is of type phalVca_Sw_DataParams_t.
[in]	bSelectionControl	[In] Value equals PHAL_VCA_ISO_SELECT_SELECTION_DF_NAME which indicates VC Selection by DF name. Any other value results in PH_ERR_INVALID_PARAMETER. Note: This parameter will be used for Software and Sam S mode only. For Sam X mode it can be neglected.
[in]	bOption	[In] Value equals PHAL_VCA_ISO_SELECT_FCI_RETURNED which indicates FCI template is returned. Any other value results in PH_ERR_INVALID_PARAMETER. Note: This value will be used for Software mode only. Sam S or X communication, The macros can be combined by oring. PHAL_VCA_ISO_SELECT_DIV_DISABLED PHAL_VCA_ISO_SELECT_ENC_KEY_DIV_INPUT PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_INPUT PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_VCUID PHAL_VCA_ISO_SELECT_MAC_KEY_DIV_INPUT_VCUID The below onse are valid for Sam X only. To be used with the bove ones. PHAL_VCA_ISO_SELECT_VARIANT_PART1 PHAL_VCA_ISO_SELECT_VARIANT_PART2
[in]	bDFnameLen	[In] Length of the IID which is nothing but DFName string provided by the user.
[in]	pDFname	[In] This is the IID which is DFName string upto 16 Bytes. Valid only when bSelectionControl = 0x04.
[in]	pDivInput	[IN] Key diversification input. This is used for SAM Key diversification
[in]	bDivInputLen	[IN] Key diversification input Length.
[in]	bEncKeyNo	[IN] ENC Key number in Software or SAM keystore.
[in]	bEncKeyVer	[IN] ENC Key version in Software or SAM keystore.
[in]	bMacKeyNo	[IN] MAC Key number in Software or SAM keystore.
[in]	bMacKeyVer	[IN] MAC Key version in Software or SAM keystore.
[out]	pResponse	[Out] Response as mentioned below. `Software:` Response received from PICC. `SAM` S : 8 bytes MAC which should be used for ISOExternalAuthenticate + Decrypted Virtual Card Data. (or) FileIdentifier `SAM` X : Virtual Card Data or FCI.
[out]	pRespLen	[Out] Response received from the PICC.

◆ phalVca_IsoExternalAuthenticate()

phStatus_t phalVca_IsoExternalAuthenticate	(	void *	pDataParams,
		uint8_t *	pInData,
		uint16_t	wKeyNumber,
		uint16_t	wKeyVersion
	)

Depending on the VC configuration, the PCD might be required to subsequently (after IsoSelect execution) authenticate itself via this command before the targeted VC becomes selected.

This command is supported by DESFire EV1, DESFire EV2 and Plus EV1 only.

Returns: Status code

Return values

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

Parameters

[in]	pDataParams	[In] Pointer to this layer's parameter structure which is of type phalVca_Sw_DataParams_t.
[in]	pInData	[In] Input buffer to be passed for authentication. `Software:` Response data (RndChl\|\|VCData) of IsoSelect command. `SAM` S : Response data (MAC + Decrypted VCData) of IsoSelect command. `SAM` X : Not Applicable. This command is not supported for X mode.
[in]	wKeyNumber	[In] Key number of the VCSelect MAC key. Only applicable for Software.
[in]	wKeyVersion	[In] Key version of the VCSelect MAC key. Only applicable for Software.

Functions

Custom Error Codes

Option to be used for ISOSelect command when called for SAM X or S configuration.

Detailed Description

Function Documentation

◆ phalVca_StartCardSelection()

◆ phalVca_FinalizeCardSelection()

◆ phalVca_SelectVc()

◆ phalVca_DeselectVc()

◆ phalVca_VcSupport()

◆ phalVca_VcSupportLast()

◆ phalVca_GetIidInfo()

◆ phalVca_IsoSelect()

◆ phalVca_IsoExternalAuthenticate()