A SP server will send requests to Fidesmo APIs to perform operations on the SE such as installing a new (Java Card) applet or storing a key on an existing one. The Fidesmo backend will translate those requests to Application Protocol Data Units (APDUs), which are commands that the SE and its applets can process. Those are then forwarded to the SE through a touch point like an app or similar.
The Fidesmo API
The Fidesmo APIs exposes operations to SPs for managing applications in remote SEs. For example, installing an application (applet) or storing a key. The operations 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 touch point.
- 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 card content management (ccm) API performs high level operations to manage applets on a card: load, install, personalize or delete applets. Our server interprets these high level operations and creates the APDU scripts that the secure chip will execute.
- The MIFARE DESfire API exposes high-level functions to deploy and manage MIFARE DESFire applications remotely: create a DESFire application, send DESFire commands to it, and delete the DESFire application.
The Fidesmo backend
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 apps and touch points.
The touch point
The app or other touch point establishing connecting to the Fidesmo backend on the SE side. This can be the consumer Fidesmo apps on Android or iOS, the Fidesmo Kiosk (retail self service tablet), before issuance with the Fidesmo Partner app, or through a third party app using the Fidesmo SDKs. The touch point is responsible for retrieving APDUs from the server and forwarding them to the SE.
The Fidesmo Service has been designed so that security is enforced by the Fidesmo components. This way, the touch point requesting the service can either be an app supplied by the SP or by any third-party without loss of integrity.
How to use the Fidesmo API
A SP will use the Fidesmo API consisting of the following two parts: The Service Delivery and the Service Operation.
1. The Service Delivery
The service delivery API part is initiated by the touch point requesting the service to the Fidesmo backend. The Fidesmo backend server will then send a ServiceDescriptionRequest to the SP, which contains a service ID identifying the service. The Service Provider responds with a synchronous message containing a Service Description structure. The Fidesmo backend will send this information to the requesting touchpoint so that it can display the information to the user and request any needed data before the service delivery starts.
Once ready the touchpoint sends a ServiceDeliveryRequest to the Service Provider though the Fidesmo backend containing the same serviceId and Service Description as 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 AKA Fidesmo ID) and a long called platformVersion.
2. The Service Operation
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 Service Delivery 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 touch point 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.
The Service Provider may send as many OperationRequests as needed by the service. When it has finished, it indicates it to the Fidesmo backend with a ServiceDeliveryCompleted API message. In the case other types of information has to be exchanged between the SP and the user through the Fidesmo API read more here.