Architecture

The Fidesmo Service combines server-side logic, accessible via the Fidesmo APIs, with a mobile client that connects the server with contactless cards using the mobile phone’s NFC capabilities. This enables security sensitive data to be handled by the backend servers and then communicated via an end-to-end channel directly to the card. This way, the applications in the phone do not need to be trusted.
The following figure shows the elements participating in the service:

Overview of Fidesmo Service

Components

  • The Fidesmo APIs expose operations to Service Providers for managing applications in remote Secure Elements.
  • The Fidesmo backend server is our highly scalable cloud-based infrastructure that prepares APDU scripts 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 Payment Service Provider: 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 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 the Service Delivery API works

The Service Delivery process is composed of two phases.

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. The Service Provider responds with a synchronous message containing a Service Description structure: the text that will be shown to the user, and the pricing information.

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

Once this process has been successfully performed, the Fidesmo Backend Server will send a
ServiceDeliveryRequest to the Service Provider, containing the same Service ID and Service Description exchanged before, plus a Session ID to be used in all messages taking part in this session.

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 ServiceOperationRequest is answered synchronously with a ServiceOperationResponse indicating that it has been accepted by the server; later on, an asynchronous callback ServiceOperationResult will contain the actual result of the operation’s execution in the card. An Operation ID links each result with the previous request/response pair, and the Session ID 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 ServiceOperationRequests 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 at the Payment Service Provider.

Depending on how the Intent was issued to the Fidesmo App, it will return a result to the 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.

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