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.
Click:
Project->Build Project
Then Click:
Run->Run
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:
>/atr
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:
>/card
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.
>auth
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) |com.st |PayPass
it basically says: install a new instance aid (A0000000041010) on the virtual card with these parameters at install time (-q C9#()) from package (com.st) class (PayPass)
and then we install the second applet class instance:
>install -i |2PAY.SYS.DDF01 -q C9#(A0000000041010) |com.st |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:
>/atr
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
0001
56 3E - Track 1 ascii
42353431333132333435363738343830305E535550504C4945442F4E4F545E30393036313031333330303033333330303032323232323030303131313130
9F64 01
03
9F62 06 - Bitmap
000000380000
9F63 06 - Bitmap
00000000E0E0
9F65 02 - Bitmap
000E
9F66 02 - Bitmap
0E70
9F6B 13 - Track 2 n format
5413123456784800D09061019000990000000F
9F67 01
03
A001 0B
00004000000000778099D3
A002 10
5229A2B1820F3213CAF2243CB19C5DF7
DE65E29F48C7F212 - MAC for this APDU-C
After the personalization command has been run, let's test one more reset:
>/atr
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 interchange....ie.:
%B4046460664629718^000NETSPEND^161012100000181000000?;4046460664629718=16101210000018100000?
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 'com.st'. I selected the com.st 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:
>test
yields:
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.
