Applications and Services

Fidesmo is all about delivering services to secure chips in contactless cards or other connected devices. Services are grouped inside applications, which are created using this Portal and are the UI elements presented to users by clients such as the Fidesmo app. There is a two-level hierarchy of concepts:

  • Applications are defined in the Fidesmo Servers through this Developer Portal and are linked to a Service Provider account. One application may have as many services as desired. Applications are the main UI element.
  • Services are defined at the Service Provider's servers (with the exception of Service Recipes which are stored in the Fidesmo servers) and they implement the actual interactions with the card or device, by sending operations to the Fidesmo API.

Service Providers can use different branding elements for applications and services to shape how they are presented to users.

Parameters to be used in service descriptions are explained here, and the process followed to deliver a service is outlined in the architecture page. The rest of this document focuses on applications.

Application parameters

Parameter Where is set Explanation
Name Dev Portal, and also API endpoint,
as part of the App Description
Identifies your application in the UI. It is a branding element. When submitted as part of the App Description, it can be given as a multilanguage string.
Service Delivery URL Dev Portal URL where the Service Provider will listen to Service Delivery Requests, see Architecture. Not necessary if using Service Recipes.
VAT Dev Portal Value Added Tax rate to be applied to your for-pay services.
Currency Dev Portal Currency used in your for-pay services
Service Description URL Dev Portal URL where the Service Provider will listen to Service Description Requests (first phase of the service delivery process), see Architecture. Not necessary if using Service Recipes.
App logo Dev Portal or API endpoint Branding element that identifies your company
Feature graphic Dev Portal or API endpoint Branding element used to display the application in the User Interface
Organization API endpoint, as part of the App Description Your company's name, to be displayed by the UI
Description API endpoint, as part of the App Description Textual description of the application. It is also a branding element displayed on the UI and must be expressed as a multilanguage string. It may contain some basic markdown elements (like emph, links or bold.
Install services API endpoint, as part of the App Description List of services that the UI will present as services that will install a "card application" on the device. See explanation below.
Uninstall service API endpoint, as part of the App Description A service that the UI will display as the way to uninstall a "card application" from the device. See explanation below.
Suspend service API endpoint, as part of the App Description A service that puts the application in a suspended state. See explanation below.
Unsuspend service API endpoint, as part of the App Description A service that brings the application from the suspended state to the normal one. See explanation below.

Example of App Description

  {
    "name": {"en": "The Secret Application",
         "es": "La Aplicación Secreta"},
    "organization": {"name": "Hidden Co Inc."},
    "description": 
      {"en": "This is an application so **secret** that we cannot tell you what it does", "es": "Esta es una aplicación tan **secreta** que no podemos decirte qué hace"},
    "installServices": ["boringInstall", "installWithSurprise"],
    "uninstallService": "deleteTotally",
    "suspendService": "suspendTheSecret",
    "unsuspendService": "bringTheSecretBack"
  }

Install/Uninstall Services

They are a User Interface concept. Applications that rely on installating applets on Fidesmo devices can define one or more services as install services and a single service as the uninstall service. This metadata is used by the client to display to users options to install or remove an application depending on its state on the Fidesmo device:

  • If an applet is not present on a device, it will display an 'install' button. Then, if more than one install service is defined, the user will choose among several options.
  • On the other hand, if it is already installed, it will show an 'uninstall' button instead.

Defining install/uninstall services is optional. However, our experiments and discussions with end users have shown that they understand much better the concept of application that can be installed or deleted from their device, due to their experience with smartphone apps.

It is important that the uninstall service removes all objects created on a card or device. For example, if other services of the same application have instantiated applets and Mifare virtual card, the uninstall service should delete the applets and remove the Mifare virtual card too.

Example

Let's imagine a security application that is based on an applet that stores a public/private keypair. This application has the following services:

  1. Install and generate 1K RSA keys
  2. Install and generate 2K RSA keys
  3. Sign a message
  4. Export public key
  5. Delete

If the install/uninstall services feature is not configured, users will see a list of equally presented services. However, if the Service Provider defines the two first services as install services and the last one as the uninstall service, the client app can show different options, depending on the application's state on the card or device:

  • Application not found: show a button to install the application. When clicked, the user will select which option (1K or 2K)
  • Application present in the card: show the list of non install/uninstall services, plus a button to remove the application.

Suspend/Unsuspend Services

They follow the same principle as the Install/Uninstall services described above. An application may need to get into a "suspended" state, as a result of an action triggered by the user (the suspend service). It will only get back to the normal state if the user first unsuspends it. What the suspend/unsuspend services actually do is up to the Service Provider: they might trigger some changes in the Service Provider's backend, in the Fidesmo device, or in both.

Defining suspend/unsuspend services is optional, but if you define a suspend service, it is mandatory to define the unsuspend service as well. The Fidesmo app will display the suspended app differently, so users can easily see the changed application state.