MIFARE Classic tutorial

Introduction

In this tutorial you will learn how to create and deploy an application that reads and writes the MIFARE Classic memory in a Fidesmo Card. The application itself is very simple: it implements a secure counter by reading a block, incrementing the value, and writing the resulting value to the same block. Finally, it sends the updated result back to the Fidesmo server to be displayed to the user. Real services are of course more complex, but we want to focus on the mechanics of how a server can participate in the Fidesmo Service Delivery process (as presented here) and execute some MIFARE operations on the card.

We have published the service's source code in GitHub. Feel free to download, modify and deploy it with your own credentials as a way to learn how to build a remote MIFARE Classic service using the Fidesmo platform.

Resources used by the example application

  • Spark, a simple web app framework in Java
  • json-simple library for JSON encoding/decoding
  • Maven as the build tool. The project can be easily imported into IDEs such as IntelliJ IDEA.
  • Heroku cloud platform for deployment

If you don’t like Java, want to use your favorite webapps framework or prefer to deploy your experiment in a different environment, feel free to change those parts of the tutorial!

Using the example application

This section shows how the service works from a user point of view. To run this section of the tutorial, you need:

The example application is called “MIFARE Tutorial App” and has two services. The first, called "Ctulhu invocation” implements the secure counter mentioned above and has been published to the application store, so it appears listed in the Fidesmo App.

  1. Open the Fidesmo App on the phone. The main screen displays a list of available applications.
    In the main screen, select the “MIFARE Tutorial App”. A list of its services appears, in this case it is just one, “Ctulhu invocation”. Press that button.
  2. Follow the instructions on screen. If you execute the service several times, you will see how the “invocations” counter is incremented.

The second service, called “Delete Ctulhu invocation”, has not been published, so it has to be called manually, as explained below. This service deletes the counter from the card.

  1. Open the Fidesmo App. Press the menu button in the upper right corner and select "Manual service order”.
  2. Enter the following data:
    • Service Provider ID: 8aaf22fe
    • Service ID: delete
  3. Press “Continue” and follow the instructions. If you run the “Ctulhu invocation” service once again, you will see that the counter starts again at 1.

Code walkthrough

In this section, we’ll see how the example application is implemented. We will constantly refer to the Fidesmo APIs and to the architecture of the service delivery process, so you’ll probably want to have those pages at hand. Off we go:

Serving the service description

When the user selects the service, the Fidesmo Server will retrieve a service description from our server.
We need to set up an endpoint to serve our description. It will return a different description for each of the two services. From all the possibilities available in service descriptions, we are just using the service title and a flag to require user confirmation (invocations to Cthulhu should not be taken lightly). If we wanted to charge for our service, or gather some customer data, this would be the place to do it.

Initiating the service delivery process

After the user has confirmed that he wants the service, the Fidesmo Server will send us a Service Delivery Request with a sessionId that we will use for each of the service operations we need to send to the card.
So let’s set up an endpoint. Depending on the serviceId, it starts with different service operations:

Let’s take a step back and see the sequence of operations we are sending in each service:

The ‘Ctulhu invocation’ service

For this service (in which we are implementing a counter,) we need to

  • Get hold of a MIFARE Classic virtual card (API endpoint /mifare/get). If the card already has a virtual card reserved for our application we can move forward, if not we need to initialize it (API endpoint /mifare/initialize).
  • Read the virtual card block where we store the counter’s value (API endpoint /mifare/read).
  • Write that same block with the incremented value of the counter (API endpoint /mifare/write).

The ‘Delete Ctulhu invocation’ service

This service is much simpler: the only operation we need to send is a request to delete the MIFARE Classic virtual card holding our counter (API endpoint /mifare/delete).

Sending an operation

As you can verify in the code, all operations follow the same pattern:

  • Prepare the JSON payload. This of course depends on the operation, as an example see the one we use for the MIFARE Read operation:

    The sector and block we want to read are encoded by a simple utility method

  • Set up the HTTP headers, HTTP method and a callback URL for the asynchronous response. All operations that interact with the card need such a callback URL; in this tutorial, /mifare/get, /mifare/initialize, /mifare/read, /mifare/write.
    This is procedure is common to all operations, so in the example service we wrote a method for it, sendOperationAndProcessResponse.
  • Check the synchronous reply to store the OperationID sent by the Fidesmo server; we will need it to match the asynchronous response to the session.

    pendingOperationsis the Map where we store the sessionId in which this operation was sent.

Checking the operation result

When sending the Read MIFARE Card operation, we specified a callback URL where the Fidesmo server will send the asynchronous operation result. So let’s write some code to process the information read from the card.

The handle method processing the request

  • uses the operationId received in the result to get the state data corresponding to the session that sent the request
  • checks the status code - if the read operation in the card failed for any reason, we would know it at this point.
  • parses the counter value using one of the utility functions
  • stores the counter in the object representing the session state
  • orders the next operation: as we know already, it is to write the new counter value on the card. If the card was just initialized, the counter will be 1.

Sending a result for the entire process

Let’s recap what our app has done at this point:

  • It got hold of a virtual MIFARE card, using /mifare/get.
  • Fidesmo then called our /gotcard callback method, which parsed the response. If the virtual card had just been created, it initialized the card using /mifare/initialize.
  • After initialization, Fidesmo called our /initialized callback method. Both that method and /gotcard (in case the virtual card had already been there) then read block 1 of sector 1 using /mifare/read.
  • Fidesmo then called callback method /readblock, which parses the data read from the card.
  • The app then incremented the counter (or initialized it) and wrote it on the same block of the card, using /mifare/write.
  • Fidesmo called callback method /writeblock with a successful status code...

When all the operations in the service have finished successfully, it is time to say goodbye with the Service Delivery Completed message, including a status code and a message to be shown to the user (API endpoint /service/completed). This is important also because it is the moment when Fidesmo will charge the user for the service (if you, as the service provider, have decided to charge for it).
In our example, the moment to do it is when processing the result from the Write MIFARE Data operation:

serviceDeliveryCompleted encodes status code and message in a JSON payload, and sends the message, this time without having to define a callback URL.

Deployment

Configuring the application in the Portal

If you are not already logged into this portal, it is time to do it (if you can’t, please do sign up!)

Go to the Applications page and select the one you want to configure. There you will find:

  • The application credentials required to send operations through the Fidesmo API. Since it is never a good idea to embed credentials in code, in the example we use environment variables.
  • A field to specify the endpoint where the Fidesmo server will retrieve the service description. In this tutorial, we are using http://[base-url]/describe
  • A field to define the endpoint to initiate the service delivery process with which we started the example application walktrough. In the example, we used http://[base-url]/deliver
  • A form to upload some elements to brand our application: a description, a logo in SVG format and a feature graphic which is a PNG or JPEG picture. They help the user recognize your application visually - in our example, nothing better than an image of Cthulhu.

Publishing a service

With the settings above, it would be possible to invoke Cthulhu manually, using the option "Manual service order” in the Android app. But we want to make things easy for our users: we want them to find this service in the application store. So let's publish it.

Have a look at these guidelines, and have your service published in the Fidesmo App Store!

Deploying in Heroku

First, you will need to create an account at Heroku. You don’t need to provide any payment details to use the free tier, which is enough for this tutorial.
Install the Heroku Toolbelt for your operating system following these instructions. Heroku Toolbelt includes the distributed version control system git, which we will also use.

As a starting point, let’s assume you have copied the service code in a directory somewhere in your filesystem, either by cloning the example service’s GitHub repository or by any other means.
Unless otherwise noted, all the instructions below are to be typed in a command line terminal from the root of that directory.

So let’s start. First, put your project under git version control

cmd> git init . cmd> git add . cmd> git commit -m "base commit"

Now create the Heroku repository

cmd> heroku login Enter your Heroku credentials. Email: funnyname@provider.com Password (typing will be hidden): Authentication successful. cmd> heroku create Creating hidden-temple-1263... done, stack is cedar-14 https://hidden-temple-1263.herokuapp.com/ | git@heroku.com:hidden-temple-1263.git Git remote heroku added

Heroku has created an empty web application (you can see it in your Heroku dashboard).
Heroku assigns a more-or-less random string to the URL pointing to your application. You can rename it to something more businesslike (note that this name needs to be unique, so if it is already chosen Heroku will return an error and you will have to pick aonther one):

cmd> heroku rename secure-counter http://secure-counter.herokuapp.com/ Renaming hidden-temple-1263 to secure-counter... done https://secure-counter.herokuapp.com/ | git@heroku.com:secure-counter.git Git remote heroku updated

That is the base URL for your application's endpoints. Don't forget to enter it as your app's Service Delivery URL in the Fidesmo Developer Portal:
http://secure-counter.herokuapp.com/deliver

To deploy, we just need to push the code to the heroku git repository. But before we need to assign values to the environment variables holding our app's Fidesmo credentials, and the base URL we have just defined at Heroku:

cmd> heroku config:set INVOKE_APPID=xxxxxxxx cmd> heroku config:set INVOKE_APPKEYS=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx cmd> heroku config:set INVOKE_ROOT_URL=http://secure-counter.herokuapp.com cmd> git push heroku master

The moment you push code to the heroku owned git repo the code gets built and deployed. Writing tutorials like this one got much easier!

The application is up and running. If you want to check it, type http://secure-counter.herokuapp.com/ in your browser's address field.
Now you can order your application's services using the Fidesmo App on your phone!

Some useful commands to check how your application is doing:

cmd> heroku logs cmd> heroku logs -t cmd> heroku ps