Architecture

Fidesmo technology enables the construction of services that, by using Fidesmo APIs, are able to manage NFC-enabled Secure Elements (SEs, aka devices) such as contactless cards through mobile phones’ NFC capabilities. This enables sensitive data to be handled by the servers (Service Providers, SP in Fidesmo’s parlance) and then communicated via a secure end-to-end channel directly to the SE. The data and operations sent between the SP and the SE are encrypted, and can be deciphered only by the SE. Even the Fidesmo sw that manages the communication with the card cannot decrypt the data it transmits. This way, the sw in the phone does not need to be trusted.

A SP will send requests to Fidesmo APIs to perform operations on the card such as installing a new (Java Card) applet or storing a key on an existing one. Fidesmo will translate those requests to Application Protocol Data Units (APDUs), which are commands that the card and its applets can process. Those are then forwarded to the SE/device through the mobile phone by Fidesmo App. The Fidesmo App manages devices and requests to SPs the execution of services. Also, optionally, it can be used by other applications in the mobile phone too, to request services execution from SPs and to handle applets in the SE. If some of these operations require a payment from the phone user to the SP this can be handled by Fidesmo’s Payment Service Provider.

The following figure shows the elements participating in this process:

Overview of Fidesmo Service

Components

  • The Fidesmo APIs expose operations to Service Providers for managing applications in remote Secure Elements. For example, installing an application (applet) or storing a key.
  • The Fidesmo backend server is our highly scalable infrastructure that transforms requests into APDU scripts to be sent to the card, and manages connectivity towards the mobile phone.
  • The Fidesmo App in the mobile phone is responsible for retrieving APDUs from the server and forwarding them to the card.
  • The Payments Handling component is a gateway to the payment/banking infrastructure. It authorizes payments, submits them for settlement once the service has been delivered, and, if requested by the user, stores the payment details for future use (Fidesmo only stores a secure token).

The Fidesmo APIs are a set of REST methods organized in two levels:

  • The Service Delivery API orchestrates a sequence of interactions between a Service Provider and a card (the “service”) as a session that is initiated from the mobile client.
  • The Service Operation APIs can be used within a Service Delivery session. Currently we provide the following operations:
    • The Transceive API transmits a sequence of APDUs to the Fidesmo backend server, to be fetched later on by the Fidesmo App and transferred to a card.
    • The MIFARE Classic API exposes high-level functions to deploy and manage MIFARE Classic services remotely: create a virtual MIFARE card, initialize it with sector trailers, read and write data, and delete the virtual card.

We plan to keep on adding operations to our APIs according to our roadmap.

The Fidesmo Service has been designed so that security is enforced by the Fidesmo components. This way, the mobile app requesting the service can either be an app supplied by the Service Provider or by any third-party, as shown in the figure above.

How to use the Fidesmo API

A Service Provider will use Fidesmo API through a process that is composed of two phases: setup and delivery.

1. Setup Phase

The setup phase is initiated by the mobile application requesting the service, which issues an Intent to the Fidesmo App (see the Fidesmo App documentation for details).

Sequence diagram of the Setup Phase

The Fidesmo Backend Server will then send a ServiceDescriptionRequest to the Service Provider, which contains a service ID identifying the service (in the Figure that ID is someService). The Service Provider responds with a synchronous message containing a Service Description structure:, text that shall be shown to the user, and the pricing information.

The Fidesmo Backend Server will use that information to ask the user for confirmation, and, if the service has a cost, to authorize the payment at the Payments Handling component once the user has entered her payment details.

Once this process has been successfully performed the Fidesmo Backend Server will send a ServiceDeliveryRequest to the Service Provider containing the same serviceId and Service Description exchanged before, plus a sessionId to be used in all messages taking part in this session. The ServiceDeliveryRequest also contains the cardId object which in turn contains a byte array called iin (Issuer Identification Number), a byte array called cin (Card Identification Number) and a long called platformVersion. There is more information available about the CIN on the Card identifying Number page.

2. Service Delivery Phase

Once the process has been set up, the Service Provider can use any of the Service Operation APIs to interact with the card. Each OperationRequest to some method of the API must contain the sessionId that was assigned in the Setup Phase, plus the callbackURL where the result will be asynchronously notified. Fidesmo’s backend will reply with the operationId assigned to that request. Then, Fidesmo Backend will send through Fidesmo App the set of APDU’s to the card to execute the operation requested. When the operation has been run an OperationResponse is sent by Fidesmo Backend Server to the URL set by callbackURL, with the operationId and final status of the execution. It can be observed that an operationId links each result with the previous request/response pair, while the sessionId assigned in the Setup Phase makes all operations part of the ongoing session.

Sequence diagram of the Delivery Phase

The Service Provider may send as many OperationRequests as needed by the service. When it has finished, it indicates it to the Fidesmo Backend Server with a ServiceDeliveryCompleted API message. If the service has a price, the Fidesmo Backend Server will then submit the previously authorized payment for settlement.

Finally, depending on how the Intent was issued to the Fidesmo App by the application in the mobile phone, it will return a result to that calling application.

Exchanging additional data between Service Provider components

In case your mobile application and servers need to exchange more information, read our recommendation here

Example Service Provider

We have created a very simple Service Provider that, after the mobile client initiates the process, sends two consecutive Service Operation Requests (using the Transceive API or the MIFARE Classic API for operations) and finally indicates that the Service Delivery session has been completed.

The source code can be found here. It is implemented using the Spray framework.

On the other hand, it is necessary that Fidesmo’s backend is aware of the Service Provider URLs. The developer must first create a Fidesmo developer account . Then, she must create a new Fidesmo application and take note of the credentials assigned to it (ID and key). That new application must be edited to set its Service Description URL (the URL where the SP will accept ServiceDescriptionRequests) and its Service Delivery URL (the URL where the SP will accept ServiceDeliveryRequests). Also, the application credentials will be necessary both by the SP and the Fidesmo App to send/handle requests for the SP services.

The example mobile client requests a service from the example SP as default.