com.symbol.emdk.securenfc

Class MifareDesfire

java.lang.Object

com.symbol.emdk.securenfc.TagTechBase

com.symbol.emdk.securenfc.MifareDesfire

public class MifareDesfire
extends TagTechBase

Provides access to MIFARE DESFire properties and I/O operations on an IsoDep Tag object. This class encapsulates all the methods required for communicating with the IsoDep tag using the tag technology protocol.

  
  Example Usage:
 public class MainActivity  extends Activity implements EMDKListener {
  
 SecureNfcManager secureNfcManager;
 EMDKManager emdkManager;
 SamType samType;
 MifareDesfire mifaredesfire;
 MifareSam mifareSam;
             
  protected void onCreate(Bundle savedInstanceState) {
  
   EMDKResults results = EMDKManager.getEMDKManager(getApplicationContext(), this);
  }
  
 public void onOpened(EMDKManager emdkManager) {
   			
  this.emdkManager = emdkManager;
  
   this.secureNfcManager = (secureNfcManager)
 				this.emdkManager.getInstance(FEATURE_TYPE.SECURENFC);
  
 	if(this.secureNfcManager != null){
  							
 	try{
  
 		samType = secureNfcManager.getAvailableSam();
 
 		} catch (SecureNfcException e) {
             						
    		e.printStackTrace();
  	}
 							
 	if (samType.equals(SamType.MIFARE)) {
 
 		mifareSam = (MifareSam) secureNfcMgr.getSamInstance(samType);
  
  }
  
    if(mifareSam != null){
         
 		try {
     	SamMode samMode = mifareSam.connect();
                        
      SamKey samKey = new SamKey();
 		samKey.keyNum = 0x00;
 		samKey.keyVer = 0x00;
 
 		mifareSam.authenticateSam(authKey, samKey,null);
 		
 	    mifareSam.close();
 
 		} catch (MifareSamException e) {
 	    	e.printStackTrace();
  	  }
 	   }
   }
 }
             
             
  public void onNewIntent(Intent intent) {
 		
 	if (intent != null)
 	   tagDetection(intent);
 	}
 
 	private void tagDetection(Intent intent) {
 		
 		if (NfcAdapter.ACTION_NDEF_DISCOVERED.equals(intent.getAction())
 				|| NfcAdapter.ACTION_TAG_DISCOVERED.equals(intent.getAction())
 				|| NfcAdapter.ACTION_TECH_DISCOVERED.equals(intent.getAction())) {
 
 			 lTag	 = intent.getParcelableExtra(NfcAdapter.EXTRA_TAG);
 
 			try {
 
 			TagTechType tagType = secureNfcMgr.getTagTechType(lTag);
 
 			if (tagType.equals(TagTechType.MIFARE_DESFIRE)) {
 	
 			mifareDesfire = (MifareDesfire) secureNfcMgr.getTagTechInstance(tagType);
 				
 			 try {
 					if (!mifareDesfire.isEnabled()) {
 
 					 mifareDesfire.enable(lTag);
 					}
 				} catch (MifareDesfireExpection e) {
 							e.printStackTrace();
 						}
 				}
 
 			} catch (SecureNfcException e) {
 			
 				e.printStackTrace();
 			}
 
 
 			}
 		}
 																				
   
   public void onDestroy() {
          
     if (mifareDesfire != null) {
 			try {
 				mifareDesfire.disable();
 
 			} catch (MifareDesfireExpection e) {
 
 				e.printStackTrace();
 			}
 
 		  }
 		if(this.emdkManager != null)
         this.emdkManager.release();
 	}
  
   
   public void onClosed() {
      this.emdkManager.release();
     }
 
  
 	}
 
 

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
class	MifareDesfire.AppKeySettings
static class	MifareDesfire.AuthenticateType Authentication mode.
class	MifareDesfire.CardVersionInfo
static class	MifareDesfire.CreditType
class	MifareDesfire.DFNames
class	MifareDesfire.FileAccessRights
static class	MifareDesfire.FileCommMode File Communication Mode.
static class	MifareDesfire.FileIDType
class	MifareDesfire.FileSettings
static class	MifareDesfire.FileType
class	MifareDesfire.FileTypeSpecificSettings
class	MifareDesfire.KeySettings
class	MifareDesfire.MasterKeySettingsType Master key setting type
class	MifareDesfire.RecordFileSettings
class	MifareDesfire.ValueFileSettings

Method Summary

Modifier and Type	Method and Description
void	abortTransaction() Invalidates all previous write access on Backup data files, Value files, and Record files within one application.
void	authenticate(MifareDesfire.AuthenticateType authType, int cardKeyNum, SamKey samkey, SamDiverseParams samDiverseParams) Authenticates card master key and application key by using SAM This is an I/O operation and will block until complete.
void	commitTransaction() Validates all previous write access on Backup data files, Value files, and Record files within one application.
void	credit(MifareDesfire.CreditType creditType, byte fileID, MifareDesfire.FileCommMode fileCommMode, int value) Increases a value stored in a value file with specified value.Depending on communication settings of file, data read from card will be either plain or enciphered.
void	debit(byte fileID, MifareDesfire.FileCommMode fileCommMode, int value) Decreases value stored in a value file with specified value.Depending on communication settings of file, data read from card will be either plain or enciphered.
void	disable() Disables I/O operations to the tag from IsoDep object and SAM communication.
void	enable(Tag tag) Enable I/O operations to tfhe tag from IsoDep object and SAM communication.
int[]	getApplicationIDs() Retrieves AIDs of all active card applications.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
MifareDesfire.CardVersionInfo	getCardVersion() Retrieves card version information such manufacturing, software and production related information.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
MifareDesfire.DFNames[]	getDFNames() Retrieves the ISO 7816-4 DF names of all active card applications.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
int[]	getFileIDs(MifareDesfire.FileIDType fileIDType) Retrieves native file IDs or ISO 7816-4 file IDs of active files within the currently selected application.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
MifareDesfire.FileSettings	getFileSettings(byte fileID) Retrieves file settings (properties) of specified file.On Tag lost connection needs to re-established by calling enable API in the application.
int	getFreeMemory() Gets total number of free user memory bytes available on card.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
MifareDesfire.KeySettings	getKeySettings() Retrieves master key settings and application key settings of selected card application or card.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
byte	getKeyVersion(byte keyNum) Retrieves current version of specified card key.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
int	getValue(byte fileID) Retrieves value stored in value file.On Tag lost connection needs to re-established by calling enable API in the application.
boolean	isEnabled() Checks if the connection with the tag is enabled or not.
byte[]	readData(byte fileID, MifareDesfire.FileCommMode fileCommMode, int readOffset, int bytesToBeRead) Reads data from standard data or backup data file.
byte[]	readRecord(byte fileID, MifareDesfire.FileCommMode fileCommMode, int recordOffset, int recordsToBeRead) Reads records from cyclic or linear record file.Depending on communication settings of file, data read from card will be either plain or enciphered.
void	resetRecord(byte fileID) Resets cyclic or linear record file to empty state.
void	selectApplication(int appID) Selects specified card application.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.
void	writeData(byte fileID, MifareDesfire.FileCommMode fileCommMode, int writeOffset, byte[] writeDataBuffer) Writes data to standard or backup data file.
void	writeRecord(byte fileID, MifareDesfire.FileCommMode fileCommMode, int recordOffset, int recordSize, byte[] writeRecordBuffer) Writes records to cyclic or linear record file.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

enable

public void enable(Tag tag)
            throws MifareDesfireExpection

Enable I/O operations to tfhe tag from IsoDep object and SAM communication. May cause RF activity and may block. Must not be called from the main application thread. A blocked call will be canceled with MiFareDesfireExpection by calling close() from another thread. Only one TagTechnology object can be connected to a Tag at a time. Applications must call close() when I/O operations are complete.On Tag lost connection needs to re-established by calling enable API in the application.

Parameters:

tag - Contactless tag already detected by device. We get this through the EXTRA_TAG information from the intent.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to enable the tag.

disable

public void disable()
             throws MifareDesfireExpection

Disables I/O operations to the tag from IsoDep object and SAM communication. Also causes all blocked I/O operations on other thread to be canceled and return with MiFareDesfireExpection.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to disable the tag.

authenticate

public void authenticate(MifareDesfire.AuthenticateType authType,
                         int cardKeyNum,
                         SamKey samkey,
                         SamDiverseParams samDiverseParams)
                  throws MifareDesfireExpection

Authenticates card master key and application key by using SAM This is an I/O operation and will block until complete. It must not be called from the main application thread. A blocked call will be canceled with IOException if close() is called from another thread.On Tag lost connection needs to re-established by calling enable API in the application. NOTE : This API must not be called from the main application thread since it is time consuming operation. Also, The application ID must be selected using the selectApplication() method before calling the authenticate() method to authenticate card with SAM.

Parameters:

authType - Type of authentication to be used.

cardKeyNum - Card key number to be used for authentication. Valid range is from 0x00 to 0x0D.

samkey - SAM key to be used for authentication.

samDiverseParams - Diversification parameters for current key. If diversification is not required by current key then this parameter should be NULL. This is not supported, hence application should pass null.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to authenticate the tag.

getKeyVersion

public byte getKeyVersion(byte keyNum)
                   throws MifareDesfireExpection

Retrieves current version of specified card key.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Parameters:

keyNum - Key number to retrieve version information.

Returns:

Returns key version.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves current version of specified card key.

  {@code
   Example Usage:
 
    mifareDesfire.selectApplication(APP_ID);
                
    mifareDesfire.getKeyVersion(keynum);
 
 

getApplicationIDs

public int[] getApplicationIDs()
                        throws MifareDesfireExpection

Retrieves AIDs of all active card applications.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Returns:

Returns application IDs.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves AIDs of all active card applications.

 {@code
  Example Usage:
 
 int[] getAppIDs =  mifareDesfire.getApplicationIDs();
 
 

getFreeMemory

public int getFreeMemory()
                  throws MifareDesfireExpection

Gets total number of free user memory bytes available on card.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Returns:

Returns the free space on the card

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to get the total free memory available on the tag.

getDFNames

public MifareDesfire.DFNames[] getDFNames()
                                   throws MifareDesfireExpection

Retrieves the ISO 7816-4 DF names of all active card applications.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Returns:

Returns ISO 7816-4 DF names and number of active card applications

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves the ISO 7816-4 DF names of all active card applications.

 {@code
 Example Usage:
          
 DFNames dfnames[] = mifareDesfire.getDFNames();
 
 

getKeySettings

public MifareDesfire.KeySettings getKeySettings()
                                         throws MifareDesfireExpection

Retrieves master key settings and application key settings of selected card application or card.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Returns:

Returns master key settings and application key settings of selected card application. Refer to KeySettings for more details.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves master key settings and application key settings of selected card application or card.

 {@code
 Example Usage:
 
 mifareDesfire.selectApplication(APP_ID);
                
 KeySettings keySettings = mifareDesfire.getKeySettings();
 
 

selectApplication

public void selectApplication(int appID)
                       throws MifareDesfireExpection

Selects specified card application.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Parameters:

appID - AID of application to be selected.

Throws:

MifareDesfireExpection

getCardVersion

public MifareDesfire.CardVersionInfo getCardVersion()
                                             throws MifareDesfireExpection

Retrieves card version information such manufacturing, software and production related information.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Returns:

MifareDesfire version information such as Software\Hardware Information such as Vendor ID ,type,version ,storage size ,protocol and Manufacturer information such as unique serial number , production batch number and production date

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves card version information such manufacturing, software and production related information.

getFileIDs

public int[] getFileIDs(MifareDesfire.FileIDType fileIDType)
                 throws MifareDesfireExpection

Retrieves native file IDs or ISO 7816-4 file IDs of active files within the currently selected application.On Tag lost connection needs to re-established by calling enable API in the application.This is a synchronous call.

Parameters:

fileIDType - Type of file IDs to be retrieved.

 {@code
  Example Usage:
 
                
  mifareDesfire.selectApplication(APP_ID);
                
 int[] getFileIDs= mifareDesfire.getFileIDs(FileIDType.NATIVE or FileIDType.ISO7816);
 
 

Returns:

Returns native file IDs or ISO 7816-4 file IDs of active files within the currently selected application.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves native file IDs or ISO 7816-4 file IDs of active files within the currently selected application.

getFileSettings

public MifareDesfire.FileSettings getFileSettings(byte fileID)
                                           throws MifareDesfireExpection

Retrieves file settings (properties) of specified file.On Tag lost connection needs to re-established by calling enable API in the application.

Parameters:

fileID - ID of file whose settings are to be retrieved. Should be within range 0x00-0x1F.

Returns:

Retrieved file setting.Refer FileSettings for more Info.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retrieves file settings (properties) of specified file.

  {@code
  Example Usage:
                
  mifareDesfire.selectApplication(APP_ID);
                
  FileSettings fileSettings = getFileSettings(fileID)
 
 

readData

public byte[] readData(byte fileID,
                       MifareDesfire.FileCommMode fileCommMode,
                       int readOffset,
                       int bytesToBeRead)
                throws MifareDesfireExpection

Reads data from standard data or backup data file. Depending on communication settings of file, data read from card will be either plain or enciphered. Preceding authentication, either with the keys specified for Read or Read&Write access is required.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - ID of standard or backup data file to be read. Should be within range 0x00-0x1F.

fileCommMode - File communication mode.

readOffset - File offset from which data is to be read. Should be within range 0x00 to (file size - 1)

bytesToBeRead - Number of bytes to be read. Should be within range 0x00000000-0x00FFFFFF. To read all the data from the specified offset, give 0 as input.

Returns:

Returns data read.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to read the data from the file.

  {@code
  Example Usage:
                
   mifareDesfire.selectApplication(APP_ID);
                
   SamKey lSamKeyForRead = new SamKey();
         lSamKeyForRead.keyNum = 0x03;// 0x51;//0x03;
         lSamKeyForRead.keyVer = 0x00;
                                                        
 mifareDesfire.authenticate(AuthenticateType.NATIVE,
               CARD_KEY_FOR_READ,lSamKeyForRead , null);
 
  //Communication type can be either Plain or Enchipered depends on the communication type 
     assigned to the application while creating on the tag .
                                                                        
        byte[] rawData = mifareDesfire.readData(STD_ID,Communication_Type,
                                                0, 0);
 

writeData

public void writeData(byte fileID,
                      MifareDesfire.FileCommMode fileCommMode,
                      int writeOffset,
                      byte[] writeDataBuffer)
               throws MifareDesfireExpection

Writes data to standard or backup data file. Preceding authentication, either with the keys specified for Write or Read&Write access is required. Should be succeeded by commitTransaction() which validates all previous write access on data files without which the changes will get invalidated.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - ID of standard or backup data file to be written. Should be within range 0x00-0x1F.

fileCommMode - File communication mode

writeOffset - File offset at which data is to be written. Should be within range 0x00 to (file size - 1).

writeDataBuffer - Buffer having data to be written.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to write the data to the file.

getValue

public int getValue(byte fileID)
             throws MifareDesfireExpection

Retrieves value stored in value file.On Tag lost connection needs to re-established by calling enable API in the application.

Parameters:

fileID -

Returns:

Returns the value in the Value file

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to retieve the value from the value file.

credit

public void credit(MifareDesfire.CreditType creditType,
                   byte fileID,
                   MifareDesfire.FileCommMode fileCommMode,
                   int value)
            throws MifareDesfireExpection

Increases a value stored in a value file with specified value.Depending on communication settings of file, data read from card will be either plain or enciphered. Preceding authentication, either with the keys specified for Credit or Read&Write access is required.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

creditType - Credit type should be normal or limited.

fileID - Value file to credited. Should be within range 0x00-0x1F.

fileCommMode - File communication mode.

value - Value by which currently stored value should be increased. Only positive values are allowed.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to credit the value from the value file.

debit

public void debit(byte fileID,
                  MifareDesfire.FileCommMode fileCommMode,
                  int value)
           throws MifareDesfireExpection

Decreases value stored in a value file with specified value.Depending on communication settings of file, data read from card will be either plain or enciphered. Preceding authentication, either with the keys specified for Debit or Read&Write access is required.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - Value file to be debited. Should be within range 0x00-0x1F.

fileCommMode - File communication mode.

value - Value by which currently stored value should be decreased.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to debit the value from the value file.

readRecord

public byte[] readRecord(byte fileID,
                         MifareDesfire.FileCommMode fileCommMode,
                         int recordOffset,
                         int recordsToBeRead)
                  throws MifareDesfireExpection

Reads records from cyclic or linear record file.Depending on communication settings of file, data read from card will be either plain or enciphered. Preceding authentication, either with the keys specified for Read or Read&Write access is required.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - Linear or cyclic file to be read. Should be within range 0x00-0x1F.

fileCommMode - File communication mode.

recordOffset - Record number from which read should start. Should be within range 0x00000000 to (existing records - 1).

recordsToBeRead - Number of records to be read. Should be within range 0x00000000 - (existing records - offset). To read all the records from the specified offset, give 0 as input.

Returns:

Buffer having read records.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to read the data from the record.

writeRecord

public void writeRecord(byte fileID,
                        MifareDesfire.FileCommMode fileCommMode,
                        int recordOffset,
                        int recordSize,
                        byte[] writeRecordBuffer)
                 throws MifareDesfireExpection

Writes records to cyclic or linear record file. Depending on communication settings of file, data read from card will be either plain or enciphered. Preceding authentication, either with the keys specified for Write or Read&Write access is required.The commitTransaction() must be called after this call which validates all previous write access on record files without which the changes will get invalidated.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - Linear or cyclic file to be written. Should be within range 0x00-0x1F.

fileCommMode - File communication mode

recordOffset - Record number from which write should start. Should be within range 0x00000000 to (records - 1).

recordSize - Size of record to be written i.e. should be equal to size of writeRecordBuffer

writeRecordBuffer - Record buffer to write

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to write the data to the record.

resetRecord

public void resetRecord(byte fileID)
                 throws MifareDesfireExpection

Resets cyclic or linear record file to empty state. Preceding authentication, with key specified for Read&Write access is required.The commitTransaction() must be called after this call.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Parameters:

fileID - Cyclic or linear file to be cleared. Should be within range 0x00-0x1F.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to reset the record on the tag.

commitTransaction

public void commitTransaction()
                       throws MifareDesfireExpection

Validates all previous write access on Backup data files, Value files, and Record files within one application. This API should be used only after executing below APIs: writeData() for Backup file credit() or debit() for Value file writeRecord() for Record file resetRecord() for Record file.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to commit the transaction on the tag.

abortTransaction

public void abortTransaction()
                      throws MifareDesfireExpection

Invalidates all previous write access on Backup data files, Value files, and Record files within one application. This API should be used only after executing below APIs: writeData() for Backup file credit() or debit() for Value file writeRecord() for Record file resetRecord() for Record file.On Tag lost connection needs to re-established by calling enable API in the application.

This is an I/O operation and will block until complete. It must not be called from the main application thread.

Throws:

MifareDesfireExpection - The exception will be thrown if it fails to abort the transaction on the tag.

isEnabled

public boolean isEnabled()
                  throws MifareDesfireExpection

Checks if the connection with the tag is enabled or not.

Returns:

true : if connection with the tag is enabled false : if the connection with tag is not enabled

Throws:

MifareDesfireExpection - The exception will be thrown if the emdk is not opened.