NAME
DesfireAPI :: Card management functions
COPYRIGHT
(c) 2009 SpringCard - www.springcard.com
DESCRIPTION
Implementation of management functions to personalize or format the DESFIRE card.
NAME
CreateApplication
DESCRIPTION
Create a new application on the DesFire card
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_CreateApplication(DWORD aid, BYTE key_setting_1, BYTE key_setting_2); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_CreateApplication(SPROX_INSTANCE rInst, DWORD aid, BYTE key_setting_1, BYTE key_setting_2); [[pcsc_desfire.dll]] LONG SCardDesfire_CreateApplication(SCARDHANDLE hCard, DWORD aid, BYTE key_setting_1, BYTE key_setting_2);
INPUTS
DWORD aid : Application IDentifier BYTE key_setting_1 : Settings of the Application master key (see chapter 4.3.2 of datasheet of mifare DesFire MF3ICD40 for more information) BYTE key_setting_2 : Number of keys that can be stored within the application for cryptographic purposes, plus flags to specify cryptographic method and to enable giving ISO names to the EF.
RETURNS
DF_OPERATION_OK : application created successfully Other code if internal or communication error has occured.
SEE ALSO
CreateApplicationIso DeleteApplication GetApplicationIDs SelectApplication
NAME
CreateIsoApplication
DESCRIPTION
Create a new application on the DesFire card, and defines the ISO identifier and name of the application
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_CreateIsoApplication(DWORD aid, BYTE key_setting_1, BYTE key_setting_2, WORD iso_df_id, const BYTE iso_df_name[], BYTE iso_df_namelen); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_CreateIsoApplication(SPROX_INSTANCE rInst, DWORD aid, BYTE key_setting_1, BYTE key_setting_2, WORD iso_df_id, const BYTE iso_df_name[], BYTE iso_df_namelen); [[pcsc_desfire.dll]] LONG SCardDesfire_CreateIsoApplication(SCARDHANDLE hCard, DWORD aid, BYTE key_setting_1, BYTE key_setting_2, WORD iso_df_id, const BYTE iso_df_name[], BYTE iso_df_namelen);
INPUTS
DWORD aid : Application IDentifier BYTE key_setting_1 : Settings of the Application master key (see chapter 4.3.2 of datasheet of mifare DesFire MF3ICD40 for more information) BYTE key_setting_2 : Number of keys that can be stored within the application for cryptographic purposes, plus flags to specify cryptographic method and to enable giving ISO names to the EF. BYTE iso_df_id : ID of the ISO DF const BYTE iso_df_name[] : name of the ISO DF BYTE iso_df_namelen : length of iso_df_name
RETURNS
DF_OPERATION_OK : application created successfully Other code if internal or communication error has occured.
SEE ALSO
CreateApplication DeleteApplication GetApplicationIDs SelectApplication
NAME
DeleteApplication
DESCRIPTION
Permanently deactivates an application on the DesFire card
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_DeleteApplication(DWORD aid); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_DeleteApplication(SPROX_INSTANCE rInst, DWORD aid); [[pcsc_desfire.dll]] LONG SCardDesfire_DeleteApplication(SCARDHANDLE hCard, DWORD aid);
INPUTS
DWORD aid : Application IDentifier
RETURNS
DF_OPERATION_OK : application deleted successfully Other code if internal or communication error has occured.
SEE ALSO
CreateApplication GetApplicationIDs SelectApplication
NAME
Desfire_GetIsoApplications
DESCRIPTION
Returns the Application IDentifiers, ISO DF IDs and ISO DF Names of all active applications on a DesFire card having an ISO DF ID / DF Name
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_GetIsoApplications(BYTE app_max_count, DF_ISO_APPLICATION_ST app_list[], BYTE *app_count); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_GetIsoApplications(SPROX_INSTANCE rInst, BYTE app_max_count, DF_ISO_APPLICATION_ST app_list[], BYTE *app_count); [[pcsc_desfire.dll]] LONG SCardDesfire_GetIsoApplications(SCARDHANDLE hCard, BYTE app_max_count, DF_ISO_APPLICATION_ST app_list[], BYTE *app_count);
INPUTS
BYTE app_max_count : maximum number of Applications DF_ISO_APPLICATION_ST app_list[] : list of Applications BYTE *app_count : number of Applications on DesFire card
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
SEE ALSO
CreateIsoApplication GetApplicationIDs
NAME
DF_VERSION_INFO
DESCRIPTION
Structure for returning the information supplied by the GetVersion command.
SOURCE
{ // hardware related information BYTE bHwVendorID; // vendor ID (0x04 for NXP) BYTE bHwType; // type (0x01) BYTE bHwSubType; // subtype (0x01) BYTE bHwMajorVersion; // major version number BYTE bHwMinorVersion; // minor version number BYTE bHwStorageSize; // storage size (0x18 = 4096 bytes) BYTE bHwProtocol; // communication protocol type (0x05 meaning ISO 14443-2 and -3) // software related information BYTE bSwVendorID; // vendor ID (0x04 for NXP) BYTE bSwType; // type (0x01) BYTE bSwSubType; // subtype (0x01) BYTE bSwMajorVersion; // major version number BYTE bSwMinorVersion; // minor version number BYTE bSwStorageSize; // storage size (0x18 = 4096 bytes) BYTE bSwProtocol; // communication protocol type (0x05 meaning ISO 14443-3 and -4) BYTE abUid[7]; // unique serial number BYTE abBatchNo[5]; // production batch number BYTE bProductionCW; // calendar week of production BYTE bProductionYear; // year of production } DF_VERSION_INFO;
NAME
FormatPICC
DESCRIPTION
Releases the DesFire card user memory
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_FormatPICC(void); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_FormatPICC(SPROX_INSTANCE rInst); [[pcsc_desfire.dll]] LONG SCardDesfire_FormatPICC(SCARDHANDLE hCard);
RETURNS
DF_OPERATION_OK : format succeeded Other code if internal or communication error has occured.
NOTES
All applications are deleted and all files within those applications are deleted. This command always requires a preceding authentication with the DesFire card master key.
NAME
GetApplicationIDs
DESCRIPTION
Returns the Application IDentifiers of all active applications on a DesFire card
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_GetApplicationIDs(BYTE aid_max_count, DWORD aid_list[], BYTE *aid_count); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_GetApplicationIDs(SPROX_INSTANCE rInst, BYTE aid_max_count, DWORD aid_list[], BYTE *aid_count); [[pcsc_desfire.dll]] LONG SCardDesfire_GetApplicationIDs(SCARDHANDLE hCard, BYTE aid_max_count, DWORD aid_list[], BYTE *aid_count);
INPUTS
BYTE aid_max_count : maximum number of Application IDentifiers DWORD aid_list[] : Application IDentifier list BYTE *aid_count : number of Application IDentifiers on DesFire card
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
SEE ALSO
CreateApplication DeleteApplication SelectApplication
NAME
GetCardUID
DESCRIPTION
Reads out the 7-byte serial number of the PICC
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_GetCardUID(BYTE uid[7]); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_GetCardUID(SPROX_INSTANCE rInst, BYTE uid[7]); [[pcsc_desfire.dll]] LONG SCardDesfire_GetCardUID(SCARDHANDLE hCard, BYTE uid[7]);
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
NOTES
This command must be preceded by an authentication (with any key).
NAME
GetFreeMemory
DESCRIPTION
Reads out the number of available bytes on the PICC
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_GetFreeMemory(DWORD *pdwFreeBytes); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_GetFreeMemory(SPROX_INSTANCE rInst, DWORD *pdwFreeBytes); [[pcsc_desfire.dll]] LONG SCardDesfire_GetFreeMemory(SCARDHANDLE hCard, DWORD *pdwFreeBytes);
INPUTS
DWORD *pdwFreeBytes : number of free bytes on the PICC
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
NOTES
This command can be issued without valid authentication.
NAME
GetVersion
DESCRIPTION
Returns manufacturing related data of the DesFire card
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_GetVersion(DF_VERSION_INFO *pVersionInfo); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_GetVersion(SPROX_INSTANCE rInst, DF_VERSION_INFO *pVersionInfo); [[pcsc_desfire.dll]] LONG SCardDesfire_GetVersion(SCARDHANDLE hCard, DF_VERSION_INFO *pVersionInfo);
INPUTS
DF_VERSION_INFO *pVersionInfo : card's version information
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
NAME
SelectApplication
DESCRIPTION
Selects one specific application for further access
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_SelectApplication(DWORD aid); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_SelectApplication(SPROX_INSTANCE rInst, DWORD aid); [[pcsc_desfire.dll]] LONG SCardDesfire_SelectApplication(SCARDHANDLE hCard, DWORD aid);
INPUTS
DWORD aid : Application IDentifier
RETURNS
DF_OPERATION_OK : application selected Other code if internal or communication error has occured.
SEE ALSO
CreateApplication DeleteApplication GetApplicationIDs
NAME
SetConfiguration
DESCRIPTION
Sends the SetConfiguration command to the DESFIRE card.
SYNOPSIS
[[sprox_desfire.dll]] SWORD SPROX_Desfire_SetConfiguration(BYTE option, const BYTE data[], BYTE length); [[sprox_desfire_ex.dll]] SWORD SPROXx_Desfire_SetConfiguration(SPROX_INSTANCE rInst, BYTE option, const BYTE data[], BYTE length); [[pcsc_desfire.dll]] LONG SCardDesfire_SetConfiguration(SCARDHANDLE hCard, BYTE option, const BYTE data[], BYTE length);
INPUTS
RETURNS
DF_OPERATION_OK : operation succeeded Other code if internal or communication error has occured.
NOTES
Read DESFIRE EV1 manual, chapter 9.4.9 for details. DO NOT USE THIS COMMAND unless you're really sure you know what you're doing!!!