Issuer‎ > ‎

Creating your first Java Card applet

What is a Java Card applet?

A Java Card applet is nothing more than a small program written for running in a payments environment like a chip card or a smartcard.

Working with Java Card applets

Because Java Card is it own programming language it is important that you have a development environment to work on in. The first thing you need to do is install the SimplyTapp Issuer SDK.

Installing the Issuer SDK

Step 1 - Download Issuer SDK- The Issuer SDK includes many applet examples as well as a simulator to test them.

Step 2 - Modify applets (if desired) and test - We provide gradle commands to make building and testing the applets easy.

SDK Layout
==========

IssuerSdkBundle directories:

- bin:
Mac/Linux/Windows scripts for "cardsim" and "gpj".

- CardApplet:
Library project for your JavaCard applets. For running and debugging,
see the dependent library list used in CardApplets/build.gradle. Your
main should be set to com.simplytapp.cardwrapper.CardWrapper.

Applet programming note: All classes needing persistent state through
the applet lifecycle must implement java.io.Serializable. Our
simulator's javacard.framework.Applet class already does this for you.
Setting serialVersionUID is not required, as state is never persisted
beyond the lifetime of an installed applet.

- CardAgent:
Library project for your applet agents

- CardAgentTesterApp:
Android application to test your applet agents. By default it tests
the the agent from the CardAgent project/directory. If you wish to
test CardAgent-PayPass or CardAgent-VisaMSD-SwipeYours, change the
dependent project in CardAgentTesterApp/build.gradle.

- CardApplet-PayPass
- CardAgent-PayPass

An extra example set of applets with an agent to perform Mastercard's
PayPass protocol.

- CardAgent-VisaMSD-SwipeYours
- CardApplet-VisaMSD-SwipeYours

An extra example set of applets with an agent to perform Visa's
MSD (Magnetic Stripe Data) protocol using magnetic stripe data
from a physical card (see the Full Circle demo on http://wiki.simplytapp.com
for additional information).

Android Studio Setup ==================== * Select "Import Project" * Select the build.gradle file in the topmost SDK directory * Use default gradle wrapper (if you have gradle 1.8 installed, using the local installation will also work). Gradle and command line builds ============================== We've included gradle files (tested with version 1.8) to help you get the SDK up in running in your IDE more quickly. Gradle wrapper, "gradlew", is provided to bootstrap Gradle version 1.8. If you already have 1.8 installed, you can just use the gradle command directly. The CardAgentTesterApp might not be able to determine the location of your Android SDK directory to build. (The error message will be clear when this is the case.) If this happens, set an environment variable ANDROID_HOME to you android SDK directory. To do a clean build of all projects, use: ./gradlew clean build The build results are in "build/" subdirectories: CardApplet/build/libs/CardApplet.jar
CardAgent/build/libs/CardAgent.jar

CardApplet-PayPass/build/libs/CardApplet-PayPass.jar
CardAgent-PayPass/build/libs/CardAgent-PayPass.jar

CardApplet-VisaMSD-SwipeYours/build/libs/CardApplet-VisaMSD-SwipeYours.jar
CardAgent-VisaMSD-SwipeYours/build/libs/CardAgent-VisaMSD-SwipeYours.jar

CardAgentTesterApp/build/apk/CardAgentTesterApp-*.apk
If you want to build just a single sub-project, execute gradlew from the project's subdirectory (1), or prefix the build target with :Subproject: (2). Example:
Method 1: [~/IssuerSdkBundle/CardApplet]$ ../gradlew build
Method 2: [~/IssuerSdkBundle]$ ./gradlew :CardApplet:build
Beside the "build" target, there is also a "clean" target and a "run" target
which will run the applet against the test.jcsh file in the applet's directory.


Eclipse (Android Developer Tools Version) ========================================= We've configured gradle to generate eclipse project files. To generate eclipse project files use: ./gradlew eclipse After that you can do File => Import => Existing Project into workspace. The root Directory is this README's directory. Uncheck "copy projects into workspace" in the event that the box is checked.

If using an IDE, you will need to set your main class to "com.simplytapp.cardwrapper.CardWrapper"

The CardApplet.jar file is now a Java Card applet package that can be uploaded to the SimplyTapp cloud.

Java Card Development

Chances are that you will want to modify or create your own Java Card applet. Here's an explanation of some of the files included in the SDK.

The project files in the package name "com.st" include:

  • CardApplet.java - Implemented payment protocol applet
  • Ppse2Pay.java - PPSE selection applet

Both of these applets include the "process" method which receives message APDU's from the POS device.

The communication from the POS follows the 7816-4 format.

	public void process(APDU apdu) {
		// Good practice: Return 9000 on SELECT
		if (selectingApplet()) {
			return;
		}

		byte[] buf = apdu.getBuffer();
		switch (buf[ISO7816.OFFSET_INS]) {
		case (byte) 0x00:
			break;
		default:
			// good practice: If you don't know the INStruction, say so:
			ISOException.throwIt(ISO7816.SW_INS_NOT_SUPPORTED);
		}
	}

Essentially the protocol looks like:
[CLA][INS][P1][P2][LC][PAYLOAD]

Generally the instruction byte [INS] is switched upon to know what the command from the POS is.

Responses from the Javacard applet should follow this format
[RESPONSE PAYLOAD][SW1][SW2]

A successfully SW1/SW2 would be 90 00

Most status words are covered here. see coding of SW1-SW2 section.

A few examples of javacard applets:

As a card credential issuer, it is important to understand how to manage the lifecycle of a card credential. The default shell with the tools provided is gpjNG..oh yeah, we went original with the "Next Generation"! gpj is a simple command line tool used to install, personalize, transact, and delete card applets in the card credential environment.

Let's look at the test.jcsh included in the SDK as an example of using gpjNG to install card applets. When debugging the project in an IDE or on the command line, your simulator should by default initialize with gpjNG as the shell and response with a header that looks like this:

# SimplyTapp simulator running on port 3000
# STShell connected on port 3000
# Connected to card NFC interface
# Welcome to gpjNG!
# type: help
# to get started
#
Found card in terminal: SimplyTapp
ATR: 3B 00 
>

The gpjNG script to personalize the example card applets looks like this:

# Using the simulator is simple. Configure your IDE to use
# com.simplytapp.cardwrapper.CardWrapper as your main class and you
# can set debugger breakpoints inside your applet for interactive testing.
#
# The most common commands that you will issue against the applet are
# included in this test script:

# Reset the card (same as /atr) and then selects default card manager:
/card

# Open a secure channel to card manager
auth

#  install -i <instance-AID> C9#([install-params]) <package-AID> <applet-AID>
#
#  Install the PPSE (Proximity Payment Secure Environment) and the specified
#  card applet to the simulator.
#
#  We allow use of a pipe symbol in these commands which converts ascii
#  symbols into hex.  For example:
#
#      |com.st      is shorthand for:  636f6d2e7374
#      |Ppse2Pay    is shorthand for:  5070736532506179
#      |CardApplet  is shorthand for:  436172644170706c6574
#
#  Our JavaCard implementation does not have a 16 character AID size limit that
#  standard JavaCard implementations have.
#
#  The first command installs the PPSE applet using its standard name
#  in widespread use on payment terminals: "2PAY.SYS.DDF01"
#  (325041592e5359532e4444463031). The C9# pararmeter personalizes the default
#  card applet ID of the point of sale applet. A0000000031010 is the
#  registered VISA AID.
install -i |2PAY.SYS.DDF01 -q C9#(A0000000031010) |com.st |Ppse2Pay

#
#  The second command installs our test applet as VISA's AID (A0000000031010).
#  This is just a stub applet that doesn't respond to any instructions.
#
install -i A0000000031010 -q C9#() |com.st |CardApplet

#  Example commands to select individual applets for testing:
/select |2PAY.SYS.DDF01
/select A0000000031010
/atr

#
#  special commands:
#       exit        - this exits the shell and simulator
#       exit-shell  - this only exits the shell but leaves the simulator running
#
#       "exit-shell" may be used to disconnect from the shell (after card setup)
#       and then re-connect from the card-agent development project
#
#exit

On to Creating Card Agent