Friday, December 20, 2013

Host Card Emulation Series: Cloud Secure Element Applet Testing

The goal of this post it to get familiar with the SimplyTapp toolset that allows you to build, deploy and test a javacard applet in a remote Secure Element architecture.

The tools used in this post closely mirror tools created by SIM card makers such as G&D and Gemalto.   So we hope you won't find them too different or cumbersome to work with.  If so, I hope this post will help the learning curve and you will be on your way with payment card applet development.
What this post will cover:
  • Compiling and testing javacard source
  • Deploying javacard applet to remote Secure Element
  • Personalization and general usage of applet running remotely
  • Using gpjNG shell tool for interfacing applet on remote Secure Element
What this post will NOT cover:
  • Using the javacard applet through a mobile application
  • Creating and using a card agent with the applet on a mobile application
  • Using HCE to deliver the javacard applet data to a terminal

So, let's download and install the Issuer SDK.  

For this post, I used Eclipse for the IDE.  So to setup my IDE, the first thing I did was run:

 ./gradlew cleanEclipse eclipse

from the IssuerSdkBundle directory.

Then run Eclipse.  
File->Import->General->Existing Project Into Workspace
select the directory "CardApplet-PayPass" from within the "IssuerSdkBundle" directory.

after project import:

This project contains the PayPass javacard applet that will run on a Secure Element.  Feel free to modify this code to see changes during testing.

Project->Build Project

Then Click:

answer the next dialog "Java Application"

answer the next dialog "CardWrapper - com.simplytapp.cardwrapper" for the main class selection

if all went correctly the console window at the bottom of the IDE should contain this:

Installing Applets:

now in the console window I can send some gpjNG commands to interact with the applet:

let's go through these commands to give a sense of what when on here.  FYI, the wiki has begun a short tutorial on gpjNG.

reset the virtual card:

The simplytapp virtual cards all come with a single root security domain managed under global platform 2.x.  so the next step is to select into that security domain.  This command automatically resets the card and selects the root security domain for us:

Next, we want to authenticate to the security domain.  The simplytapp virtual card does not need the concept of "installing for load" as defined in global platform because the load file is already present in the virtual card through the .jar file in the simulator and then later in the same .jar file when it is uploaded to the cloud.  The authenticate command uses the default security domain commands of the virtual card to authenticate to it.

After successful authentication to the security domain we are able to run GP "install for install" commands in order to install instantiation(s) of the applet into the virtual card.  Our test applet .jar in this example has two classes that extend Applet class:  Ppse2Pay and PayPass.  Each of these applet's can be instantiated into the virtual through the GP "install for install" command.
>install -i A0000000041010 -q C9#(01541312ffffffa86a3d06cae7046a106358d5b8239cbe89aa7f00) | |PayPass

it basically says:  install a new instance aid (A0000000041010) on the virtual card with these parameters at install time (-q C9#()) from package ( class (PayPass)

and then we install the second applet class instance:
>install -i |2PAY.SYS.DDF01 -q C9#(A0000000041010) | |Ppse2Pay

Now we can test our newly installed applets by selecting each of their AIDs:
>/select |2PAY.SYS.DDF01

>/select A0000000041010

if each of these commands responds with the last two byes (status word) of 90 00, then all went well for installing the applet. 

Personalize the applets:

Before we can try executing a transaction against the newly installed applet pair, this PayPass applet requires a personalization step to advance the applet state to personalized and the same time the personalization script injects all the card holder specific data into the applet.  here is a routine that can be used to personalize a PayPass applet:

Again we reset the card first:

There is not need to authenticate to the security domain this time because the paypass spec does not define that is a requirement and the applet itself maintains the personalization channel independent of the GP secure channel.  So the next step is to select into the applet ait:
>/select A0000000041010

And finally, as the applet instance has not been personalized yet, a single personalization command can be issued to the applet.  
>/send 84E2A000AB01017F9F6C020001563E42353431333132333435363738343830305E535550504C4945442F4E4F545E303930363130313333303030333333303030323232323230303031313131309F6401039F62060000003800009F630600000000E0E09F6502000E9F66020E709F6B135413123456784800D09061019000990000000F9F670103A0010B00004000000000778099D3A002105229A2B1820F3213CAF2243CB19C5DF7DE65E29F48C7F212

The paypass specification defines the data in this command, but we can parse it out to have a better understanding of what is being sent. It is typical TLV format after the APDU header:

84 E2 A0 00 AB      
0101 7F - DGI 
 9F6C 02
 56 3E - Track 1 ascii
 9F64 01
 9F62 06 - Bitmap
 9F63 06 - Bitmap
 9F65 02 - Bitmap
 9F66 02 - Bitmap
 9F6B 13 - Track 2 n format
 9F67 01
 A001 0B
 A002 10

DE65E29F48C7F212 - MAC for this APDU-C

After the personalization command has been run, let's test one more reset:

and then one more applet select:
>/select A0000000041010

Trying a transaction:

at this point, we can test a full transaction against the personalized card applet.  in general the reader will execute these commands in this order for PayPass:
1)  Select PPSE:                                     /select |2PAY.SYS.DDF01
2)  Select Applet AID:                           /select A0000000041010
3)  Get Processing Options:                   /send 80A8000002830000
4)  Read Record:                                    /send 00B2010C00
5)  Compute Cryptographic Checksum: /send 802A8E80040000089900

The trace above shows a successful PayPass interrogation from a terminal reader.  The data in the response APDU's is used to collate the resultant Track 1 and Track 2 data that is processed over the


Packaging the applet:

In eclipse, select the packages you would like to export as a jar file.  In the example, I expanded the 'src' directory to show the package ''.  I selected the package and then clicked 'File->export':

Expand the Java folder in the dialog box and select "JAR file", then click "Next >"

Select a name and destination to put the jar and click "Finish".  In this example i selected PayPass.jar as the name and opted to export it to my desktop.

Because this demo does not discuss building and testing a card agent and the card agent .jar file is also required to upload with the card applet .jar file, let's just use the available card agent from GIThub for the paypass applet.  it can be found here:  CardAgent.jar .  please download this to your desktop.

Upload applet to the cloud

Now that we have both the PayPass.jar (card applet) and CardAgent.jar (card agent).  We can load the card applet into the cloud.

Open a browser window and browse to create an issuer account at this link:
If you do not have a simplytapp account, you will have to click the "sign up" link on this page first.

For this example select a name for your new Issuing Entity and a logo I used the name "Test Bank".  Feel free to use the generic cloud logo here:  cloud.png,  just download it to your desktop as well.

After clicking "Create Entity", you will be directed to the Issuing Entity control panel:

Now, expand the issuing entity control bar and then click the "New Brand" button in the expanded bar:

  • Enter the name of the card brand you would like to create (ST PayPass)
  • Upload a card brand image icon...pick what you want, or just use the cloud icon again (cloud.png)
  • Select an acquire card URL based on where the registration wizard would begin for this card brand.  Just make something up as we will not use this for anything in this demo.
  • Select a version number of your choice (1.0)
  • Then upload both the Applet Jar (PayPass.jar) and the Agent Jar (CardAgent-PayPass.jar) with the "Choose File" buttons.  
  • Then click the  "Create Brand" button.

On the resulting page, expand the "ST PayPass card brand, and click "Get Test Card" button.
Expanding "ST PayPass" will give you a screen that looks like this:

We are now interested in the Test Utility (STBridge.jar) and the utility connection data:

java -jar STBridge.jar -ck J0VHTtI0EabBTp48HGj1HNbEywLAHlTDNuhhFbG3 -cs SNNLiCZnlumhHAm3tMbSbsKtwX4OAsecjzOjL5Rq -at I8IvjpTdjcMXPVkDZmgU6BcwcsfnXE4TFnWBQzTR -ts KnCyYA3r8cp15IxaT2i4Kqal8cwwbwen7VS15ujt

after running the above command your shell should look something like this:

at this point my shell is connected to the remote card and I have the ability to issue commands at well to the cloud virtual card.  This time let's try to run a personalization script through the shell.  Here is a link to a test script for download:

this particular test script first personalizes the paypass card and then preforms a transaction against that same card.  The script path can be set within the shell tool:
>/set-var path=../CardApplet-PayPass/

And then any script in that directory including the test.jcsh can be run by simply entering the script name as the command without the .jcsh extension:


As you can see this script was run against a remote cloud card.  The APDU trace is a standard APDU trace for a typical paypass credential and the timings for each are displayed under the execution of each command.  Just FYI, our office location for this test is Austin, Texas (where the script was run), but the cloud card is actually located in Dallas, Texas.  Latencies probably reflect as such for each command.

Stay tuned for future blogs that would demonstrate how to leverage this remote card inside an HCE android application.  


  1. Hi Guys,

    I am trying to follow the process given but the problem i am facing is the link is not working , whether the link is same as, if so then i am not able to run ./gradlew in the IssuerSdkBundle folder as it is giving the error
    -bash: ./gradlew: No such file or directory

    So please reply back with the response.


    1. This comment has been removed by the author.

  2. Such an elaborately detailed article this is! I mean you have made sure that even a novice can take advantage from your post. Well done!