Applications and Services

Fidesmo is all about delivering services to Secure Elements (SE) such as 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 end-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 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 end-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

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"
  }

States of an application

From the end-user perspective, an application has 4 possible states: Non-installed, Installed, Suspended and Unstable. Possible state transitions are shown in this diagram:

• Not-installed applications are known to the Fidesmo app but have not installed any content on the SE.
• Installed applications are those that have installed some contents in the SE (an applet, DESFire app, ELF).
• Suspended applications are those that were installed but later on suspended. The actual semantics of suspension depend on the application, it is possible that suspended applications still keep elements in the SE.
• Unstable is a contingency state, reached when Fidesmo stack cannot confirm that the application is in any of the other states. Users should not try to use such applications, instead they should be uninstalled.

State transitions and Purging

A transition between two states is usually triggered by the delivery of some application service, which is run by its Service Provider (see sections Install/Uninstall services and Suspend/Unsuspend services below).

Install/Uninstall Services

Applications that rely on installing elements (applets, DESFire apps…) on Fidesmo SEs can define one or more services as install services and a single service as the uninstall service. Whenever an install service is run against a device, Fidesmo mobile app will show that app as installed in the device to the end-user (state installed). This way, end-users are aware of the actual content of the SE.

If an application is not installed Fidesmo mobile app will show the install services available, likewise if the application is installed then Fidesmo mobile app will show the uninstallation service. The uninstall service can only be invoked for installed applications; likewise an install service can only be invoked for apps that are in non-installed state. Invoking those services from any other state will get an error from Fidesmo backend. Also, if the delivery of either install service or uninstall service fails then the application is marked as unstable.

Service developers should label as install service all those services that store some element (applet, ELF, DESFire app) in the SE. If a service that is not an install service stores some element in the SE the application is left in the unstable state. Likewise, removing some element from the SE outside an uninstall service will also left the application in the unstable state. These are the Fidesmo API endpoints that add/remove elements to the SE when invoked:

• Endpoints that add elements: /ccm/install, /ccm/load, /desfire/ev1/createApp
• Endpoints that remove elements: /ccm/delete, /desfire/ev1/deleteApp

Note that after the invocation of the uninstall service, regardless of the actions taken by the SP, Fidesmo backend will try to purge all elements in the SE that were installed by that application (ELFs, applets, DESFire apps…) no matter which service wrote them (installation service or otherwise). That way, when an application is shown as not installed by Fidesmo app, the end-user can be sure that no element from that application is in the SE.

Defining install/uninstall services is optional. However, our experience dealing 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.

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, end-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 SE or device:

• Application Non-installed: show a button to install the application. When clicked, the end-user will select which option (1K or 2K)
• Application Installed: show the list of uninstall services. When an option is clicked uninstallation service will be run, afterwards Fidesmo backend will purge all possible remaining elements of the app in the SE

Suspend/Unsuspend Services

An installed application may need to get into a suspended state, as a result of an action triggered by the end-user (the suspend service). It will only get back to the installed state if the end-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. Only installed applications (see previous section) can be suspended, Fidesmo backend will reject to run a suspension service on non-installed applications. Also, if the application is suspended, the Fidesmo app will only allow to invoke the unsuspend service or the uninstall service (if present). Trying to invoke any other service on a suspended application will return an error from Fidesmo backend to the requester. Finally, if the delivery of the suspend service or the unsuspend service fails then the application is left in the unstable state.