Monday, December 23, 2013

Host Card Emulation Series:User Experience

Getting a Feel for the User Experience: Example of the Initial Authorization Process 

Available with the mobile SDK download from SimplyTapp.

This post is meant to show and explain what a user's initial authorization experience might look like. Keep in mind that this is a user experience example only and the SimplyTapp Mobile SDK has already been integrated with the user's third party app.

The following post will take you through the initial authorization process and explain what is happening along the way. At the end you will have a independent third party app that will be loaded with one authorized payment card and will be ready for "tap and pay" use at contact-less terminals, like McDonald's.

Lets begin

User launches your app (clicking on the app icon from the phone screen)

The picture below illustrates what the user experience would look like from within the app.  The process is based on existing Open Authentication standards.  The application must first ask the user if they would like to approve the application for making payments with a payment card at a P.O.S. terminal.

 * Any SimplyTapp branding is purely for demo purposes. Branding would be replaced by issuing entity.

In the back end this is the process that goes on;  The box on the right side is typically a browser that verifies to the user that the application is authentic and that the application would like to ask permission to present payment cards as a form of payment at a P.O.S.  Upon user approval, the application will ultimately end up with an access token and secret that can be used only to allow transactions against a remote card, but not manage the card itself.

User Sets Pin

After you have successfully logged in and authorized the application  you will be brought from the browser back to the mobile app. You will be prompted to create a new 4 digit pin. This pin is for our newly added payment functionality and can be used instead of storing any Open Authentication secrets on the handset itself.  The pin is never stored locally on the handset and is used as a quick password entry.

In the background the open authentication process is used to synchronize the user's new pin with the token secret:
At this point the mobile application is approved by the user to make point of sale payments with any cards that it may contain.  The app itself does not contain any cards yet as the customer has not applied or registered for any digital cards.  In a similar process, the user is made aware that the app currently has cards available, but the user must apply for them.

User gets their first Card

The user has the ability to apply for cards from issuing entities. Simply Bank is a demo page set up to illustrate and provide a walk through for issuer card holder relationships.  Here you can load specific card from SimplyBank and then navigate back to home screen of app.  The process is similar to the approval process of the app to present cards for payment.  The main difference being the user must approve the issuing bank to place a card in the mobile application.  The user will be pushed from the mobile application to the issuing bank registration web page:

In the background, the card acquisition process is represented like this.  Ultimately, the personalized card is represented in the same format as an EMV chip card, however the data is stored remotely inside a secure vault instead of in a localized SIM chip:

User pushed back to their App and ready to pay

Once a payment card is acquired, you will view and navigate app as normal. In this example we can check balances and manage our money exactly the same as before with app.  The payment feature can happen in the background by simply tapping the phone to a payment terminal at any given time.

In the background, the payment process is triggered by an interrupt from the terminal and can happen at any time.  To be prepared, the mobile application has pre-fetched payment terminal data to use when making a payment.  This fetching process can happen at any time prior to the first tap and may consist of one or more tokens to be used for payment depending on configurations by the issuer:

Extra Info

Below are the logs from payment process happening on the back end.. These logs are part of the U.I. from the SingleCard app.

This example app is now fully authorized and ready for secure contact-less NFC payments.
SimplyTapp's developers wiki is available at

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.