Additional JCOP on-card API: Mifare™ API

Introduction

Certain versions of JCOP feature an applet programmer's interface (API) that is beyond the scope of the APIs described in the general specifications. When present, the API described in this document is primarily concerned with access to the Philips Mifare™ data structures contained in the JCOP3, i.e., the dual-interface, versions of JCOP cards running on Philips P8RF5016 controllers.

This document describes this Mifare™ API. It is not of relevance for other purposes and should then be disregarded.

Mifare™ is a specification owned by Philips Semiconductors, and any questions concerning its operation should be directed to Philips.

Package

The code for accessing the Mifare™ data sections is contained in the class

jz.framework.JZSystem

Any code that shall make use of this API has to import this class.

Constants

• JZSystem.MIFARE_PASSWORD_READ: read data from a given Mifare block
• JZSystem.MIFARE_PASSWORD_WRITE: write data to a given Mifare block

Method

short JZSystem.readWriteMifare(short mode, byte[] data, short offset, short mifareBlock)

The parameters have the following meaning:

• mode: read or write access as defined with the two constants MIFARE_PASSWORD_READ or MIFARE_PASSWORD_WRITE
• data: Data storage in RAM holding the (8 byte) Mifare Password and providing further 16 bytes of space to carry the data to be read or written
• offset: Offset into the data storage provided above, indicating where the first byte of the Mifare Password (8 bytes) resides. Depending on the mode, the 16 bytes after the Mifare Password contain either the data to be written to the Mifare sector, or will contain (after return from the function) the 16 bytes of the Mifare block read.
• mifareBlock: Identifies the Mifare block number to be read or written. In JCOP, this number can range between 0 and 63 (1kB Mifare configuration). No Mifare sector trailers (Mifare block number % 4 == 3) can be read. Any block but block 0 can be written.

The method returns a (short)0, if access was successful, a negative value otherwise. An ArrayOutOfBoundsException may be thrown if an insufficient amount of RAM was presented: The mathematical precondition for the method to work correctly is
offset + 24 < data.length.

Sample Code

Sample code making use of this API is listed below:

import jz.framework.JZSystem;

[...]

byte[] buf = apdu.getBuffer(); // assume APDU buffer contains Mifare password

// set up Mifare Password (8 bytes) for Mifare block 4 at offset 12 into buf.

// ... check Philips documentation on how to create Mifare Password...

if (JZSystem.readWriteMifare(JZSystem.MIFARE_PASSWORD_READ, buf, (short)12, (short)4) != 0)
    ISOException.throwIt(ISO7816.SW_SECURITY_STATUS_NOT_SATISFIED); // Mifare rejected access

// If Mifare Password is OK, expect 16 bytes of block 4 to present in buf at offset 20..36


Caveats

It has to be noted that code written against this API will only run on JCOP3 cards. It will not run on generic JavaCard/OpenPlatform compliant cards, and it will also not run on JCOP10 or JCOP20 cards. The error condition reflecting this will be a failure to load the applet containing this code. This is due to a reference to the Mifare™ code in the Export File (cf. JavaCard Specifications for further explanations on this) which will be reflected in the CAP file generated.

The handling for block 0 is special in one regard from the handling of the other blocks: Block 0 contains the Mifare ID, and hence, is freely readable (without password). Therefore, the result of a MIFARE_PASSWORD_READ access to block 0 is returned at the actual offset location specified above.

Related specification

In order to make use of the Mifare™ API, it may be necessary to know how the Mifare Password is generated from the Mifare Sector Keys. A companion document from Philips Semiconductors describes this algorithm: It is available in this distribution and accessible over this link (Reproduced with permission of Philips Semiconductors BU ID). When reading the specification, equate 'User OS' with 'JCOP' to aid the understanding in this context.