1. Development Kit User Guide
  2. Setup, Samples and Tools
  3. Running the Samples
  4. Running the reference_apps Samples

Running the reference_apps Samples

The following sections describe the reference applet demonstrations and how to run them:

  • Biometry Sample Application - Demonstrates the use of the biometric APIs of type PASSWORD.

    See Biometry Sample Application.

  • JavaPurseCrypto Sample - Demonstrates the use of a DES MAC algorithm.

    This sample is only included in bundles with cryptography extensions. See JavaPurseCrypto Sample.

  • PurseWithLoyalty Sample Application - Demonstrate the use of shareable interfaces.

    See JavaPurse Sample Application.

  • Transit Sample - Demonstrates a contactless card-based transit applet and its interaction with a turnstile transit terminal and with a point of sale terminal.

    This sample is only included in bundles with cryptography extensions. See Transit Sample.

Biometry Sample Application

In this sample, a user password is enrolled on the card and a candidate password is matched against the enrolled password. The sample demonstrates the basic functionality of the biometric API. In the sample, everything works well. Non-sample code should be prepared to handle errors that may occur during the enrollment process or the matching process, including a card-blocked state, or a non-initialized state. See How the Biometric API Works.

  1. The off-card tool takes a hard coded password and sends it to the card for enrollment. For this sample, the off-card tool is a simple apdutool script used for both enrolling and matching.

    The applet selected on-card is the SampleBioServer applet. See SampleBioServer Class.

  2. The SampleBioServer applet stores the password as the reference template with five tries allowed before block.

  3. For matching, the APDUscript asks the on-card client (SamplePasswdBioApplet) to ask the SharedBioTemplate for the public template.

    For this sample, the public template only contains the version number of the implementation and the length of stored password representing the requirement for password capture. See SamplePasswdBioApplet Class.

  4. The script sends the same password that was used for enrollment.

    The card has a matching algorithm and calculates the score based on the stored password and received password.

  5. The card returns "verification successful" to the script.

Follow one of these sets of instructions to run this sample:

SampleBioServer Class

This class represents the BioServer applet on the card. This class is the interface to the on-card and off-card clients for the biometric functionality on the card.

It communicates with off-card clients with APDUs, and with on-card client applets with an implementation of SharedBioTemplate. This class causes the enrolling of the biometric password while communicating with an off-card tool that sends the password to the BioServer.

SamplePasswdBioApplet Class

This represents an on-card client applet for the password biometric sample. It communicates with an off-card tool to get the password and calls the match method on the ShareableBioTemplate reference it gets from the Java Card runtime environment, which is given the SamplePasswdBioServer applet AID.

How the Biometric API Works

The biometric API provides three basic functions:

  • Match biometric information on-card

  • Enroll users off-card and transfer their information on-card

  • Verify the user in a sequence of off-card and on-card interactions

On-card Matching

Biometric verification must happen on-card for security reasons. The card cannot send out a person's biometric information or a PIN for verification to be done off-card; it would not be secure to do so.

Enrollment Process

During the enrollment process, a person's biometric information is captured off-card and then transferred on-card for storage and verification purpose. Since Java Card technology-based cards are generally limited in their resources, the entire data captured off-card is not sent to the card. What is sent is a digested version of the biometric data and is very specific to a particular algorithm. For this sample, however, a password is small enough that the entire password is transferred to the card.

The user-specific data transferred makes up a reference template that is used later for verification. At the end of the enrollment process, there also exists an associated public template. The public template consists of information for the off-card tool to capture the relevant information from the user during verification.

For example, in the Precise Biometrics implementation of the fingerprint biometric API, the public template contains the coordinates, relative to the reference point for capturing fingerprint information. The off-card tool looks at these coordinates and extracts that information from the user. The public template defines the data requirements for verification. For this sample, the public template does not contain any such specification since the entire password is compared. In the sample, the public template just contains version information.

Verification Process

During the verification process the user enters biometric information into a sensor or input device. The information gathered from the user input is defined by the public template (see Enrollment Process). This information might be pre-processed off-card and transferred to the card for verification. The on-card biometric application performs the verification given the reference template with pre-existing user information and the new information that came in. The following describe the verification sequence:

  1. The host issues a verification request to the card.

  2. The card returns the public template to the host.

  3. The host captures user information and extracts the data defined by the public template.

    The host might perform data-processing specific to the biometric algorithm.

  4. The host sends extracted verification data to the card.

  5. The card matches the captured data with its own representation stored in the reference template.

    The matching process results in a score of how well the user information matches the reference template information.

  6. The card compares the score with the threshold for acceptable criteria and returns the verification result to the host.

Implementation Notes

The following restrictions apply for the Oracle implementation of the password biometric:

  • The minimum password length to be enrolled must be 5 bytes.

  • The maximum password length to be enrolled must be 50 bytes.

The array containing password data during enrollment or matching must have the password laid out as a byte array with each character represented by a byte starting from index offset. There can be no other information in the byte array from index offset to index offset+length-1. For example, password "tests" must be represented by the byte array {116, 101, 115, 116, 115} starting at index 0 with length 5.

The public template for the stored password returned during a matching session is a byte array (dest) with formatting as shown below. The version for this implementation is 1.0.0, so the dest array would be as follows, where passwd length represents the length of the enrolled password.

  • dest[0]=1

  • dest[1]=0

  • dest[2]=0

  • dest[3]=passwd length

Running the Biometry Sample in Eclipse

The Biometry sample consists of two Java Card projects: Biometry_Client and Biometry_Server. We will run them without the APDU console.

Start Eclipse. Sample_Platform and Sample_Device must already be created.
  1. Import the Biometry_Client and Biometry_Server projects into your workspace. If the builds don’t start automatically, start them manually.
  2. Before you start any script, you must change the PowerDown and PowerUp parameters for generating the script files. Otherwise, the simulator goes into the PowerDown mode or interrupt the execution by throwing error messages.

    To change the PowerDown parameters in the Biometry_Server project :

    1. In the Package Explorer view, click Biometry_Server Java project.
    2. Right-click on the Java Card project and select Java Card and CAP Files Settings.
    3. Select a CAP file from the list that appears in the Java Card CAP Files page.
    4. Click Biometry_Server and select Edit.
    5. In the Edit mode, select Compact CAP File.
    6. Click Next>.
    7. Select ScriptGen slide and select the Suppress "PowerDown;" APDU command at the end of CAP script check box.
    8. Click Finish and select Apply and Close.

    To change the PowerDown parameters in the Biometry_Client project :

    1. In the Package Explorer view, click Biometry_Client Java project.
    2. Right-click on the Java Card project and select Java Card and CAP Files Settings.
    3. Select a CAP file from the list that appears in the Java Card CAP Files page.
    4. Click Biometry_Client and select Edit.
    5. In the Edit mode, select Compact CAP File.
    6. Click Next>.
    7. Select ScriptGen slide and select the Supress "PowerUp; APDU command at the beginning of CAP script and Suppress "PowerDown;" APDU command at the end of CAP script check boxes.
    8. Click Finish and select Apply and Close.
  3. Right-click on Biometry_Client, select Properties, select Run/Debug Settings, click New.... The Select Configuration Type window opens. Select Java Card Project Run, click OK.
  4. In the Edit Configuration dialog:
    1. In the Name field, enter Biometry
    2. Select Start simulator.
    3. In the Scripts to be executed on simulator list box, add the following scripts:

      • cap-com.sun.jcclassic.samples.biometryserver.script from Biometry_Server

      • cap-com.sun.jcclassic.samples.biometryclient.script from Biometry_Client

      • biometryEnroll.scr from Biometry_Client

      • biometryMatch.scr from Biometry_Client

    4. Click Apply and Close
  5. In Java Card View, double-click on Sample_Device. In the Properties for Sample_Device dialog, select the CREF tab:
    1. Select Do not open APDU console.
    2. Click OK.
  6. In the top menu, select Run and Run Configurations..., select Biometry and click Run.

    Compare the output with the contents of the biometry-client.expected.out file.

Running the Biometry Sample from the Command Line

  1. Open a Command Prompt window and perform the following:

    1. Navigate to the JC_HOME_SIMULATOR\bin directory.

    2. Start the simulator by using the following command at the command prompt:

      cref -o e2p

    The simulator saves the EEPROM contents to a file named e2p.

  2. Open a second Command Prompt window and perform the following:

    1. Set ANT_HOME (path to ant install folder), JC_HOME_TOOLS and JC_HOME_SIMULATOR (path to JCDK install folder) as environment variables.

    2. Navigate to the JC_HOME_SIMULATOR\samples\reference_apps\Biometry\Server\applet directory.

    3. Enter the following command at the command prompt:

      ant all

      In this sample's applet directory, the ant all command executes the APDU script and installs the secure RMI application.

  3. In the cref Command Prompt window, restart the simulator by using the following command:

    cref -i e2p

    The simulator uses the contents of the e2p file to initialize the EEPROM.

  4. In the applet Command Prompt window, perform the following:

    1. Navigate to the JC_HOME_SIMULATOR\samples\reference_apps\Biometry\Client\applet directory.

    2. Enter the following command at the command prompt:

      ant all

      In this sample's client directory, the ant all command executes the APDU script.

  5. Verify that the output displayed in the Command Prompt window is the same as the contents of the biometry-client.expected.out file.