This page explains how Fidesmo exposes the Java Card functionality of Secure Elements (SE). Java Card is a software technology that enables a developer to write programs that use the processor of the SE. A Java Card application is in the rest of this chapter referred to as a Cardlet.
SEs with Fidesmo implement a security architecture based on GlobalPlatform 2.1.1. The Issuer Security Domain (ISD) is controlled by Fidesmo, and all other Service Providers installing their cardlets onto the SE receive a Security Domain (SD) of their own. This means that all Service Providers’ applications and data on the SE are sandboxed: No Service Provider can access other Service Provider’s applications nor data.
The core of the Fidesmo Java Card offering is the five RESTful API endpoints. Three of them are used to manage CAP files in the Fidesmo backend, and two of them are used to interact with the SE.
In order to install a cardlet on a SE it must be uploaded to the Fidesmo backend first. The uploaded cardlet can then later be installed on any number of SEs. Currently we only accept cardlets in the converted applet format (usually referred to as CAP). When using the REST Api for uploading your cardlet the Fidesmo backend will check that the cardlet complies to all the restrictions given in this document and might reject the uploaded file. You might update an uploaded cardlet at any time, but it will only affect new installations of your cardlet. In the Fidesmo backend the cardlets are identified by their AID, which is needed for further operations like installing and uninstalling it from cards, as well as deleting it completely.
You might need to upload several versions of a CAP file, depending on what version of JavaCard, GlobalPlatform or the card’s Operating System the applets are compiled against (to know the available options, please see the /executableLoadFile operation in the Fidesmo API)
The Fidesmo server will choose the version that fits better in the current device at installation time.
The ccm/install endpoint is used to install a cardlet corresponding to a CAP file previously uploaded to the Fidesmo backend. This endpoint first creates an SD for the Service Provider, then loads the cardlet and finally instantiates it. The endpoint is idempotent, meaning that any of these steps are avoided if they have been performed previously and continues from the first step which is not already done (i.e., if there is already an SD present, it is not created, and if the cardlet is already loaded, the cardlet is not loaded etc.). In GP terms, the operations performed are INSTALL[for load] and INSTALL[for install and make selectable].
You can use the ccm/storedata endpoint to personalize (load keys and data) a cardlet securely, that is, establishing a secure channel to the cardlet. The content of each data element (DGI or TLV) can be encrypted additionally.
The ccm/delete endpoint is used to delete a cardlet residing on the SE. It starts with deleting the instance, and if there are no remaining instances corresponding to a loaded cardlet, it also deletes the loadfile, and if there are no remaining cardlets in the SD, it deletes the SD as well.
In order to facilitate the development process Fidesmo has developed an open-source utility called FDSM. It is a full command-line client, so you can test the full Service Delivery Process, and also a tool for applet development, testing and managing your application and associated applets in the Fidesmo platform.
The AID (Application Identifier) identifies a CAP file, an applet, or an applet instance. Fidesmo provides an AID prefix for each Developer on the Fidesmo platform. Our APIs also enforce the usage of those prefixes by default (see next section for exceptions). A Developer may freely choose AIDs from the following pattern: A0:00:00:06:17:00:${application id}:${custom suffix smaller 6 bytes}
We require that all applet AIDs must be a suffix of the AID of their CAP file. In addition we consider it good practice to use the custom suffix for name spacing and versioning. And if there is only one instance of an applet, using the same AID for applet and instance is also considered good practice.
In practice, this restriction means that your cardlet will only be able to be uploaded, installed, instantiated, and selected using those AIDs.
In case you want to use an AID that does not follow the format above, please contact us. After verifying that you are indeed entitled to use that AID (by proving the ownership of the RID on which the AID is based, or because your service uses a standard AID), we will register it for you in the backend.
Please note that manual AID assignment can be used only for applet instance AIDs. Loadfile (ELF) AIDs must comply with the format described above. This has the following consequences:
When installing an applet using the “non-standard” AID, you still have to use AIDs compliant to the format above for the Loadfile and Load Module. Here is a fragment of a service recipe that calls the ccm/api endpoint to instantiate an applet with a reserved RID of D276FFFFAA0101. The Service Provider’s appId is FFCAFE00.
"actions": [
{
"endpoint": "/ccm/install",
"content": {
"executableLoadFile": "A00000061700FFCAFE0001",
"executableModule": "A00000061700FFCAFE000101",
"application": “D276FFFFAA010101"
}
}
]
When deleting an applet that has a “non-standard” AID, it is necessary to delete its ELF, setting the withRelated parameter to true. For example, see this piece of a service recipe that would delete the applet instantiated above:
"actions": [
{
"endpoint": "/ccm/delete",
"content": {
"application": "A00000061700FFCAFE0001",
"withRelated": true
}
}
]
Due to the special characteristics of the smartcard environment, it is necessary to follow these guidelines when developing Java Card software:
install() method. Objects shall be instantiated once during the applet lifetime, during applet initialization. In the rest of the code, reuse objects instead of instantiating new objects.JCSystem.requestObjectDeletion(). It might be interrupted by a power loss, damaging the card.In order to run on the current Fidesmo Cards and to be portable to future revisions, your applet needs to follow these guidelines:
The JavaCard and the Smartcard domain are using different names for the same entities. To avoid misconceptions lets define a common vocabulary: A JavaCard application is distributed to a Smartcard as a package in converted applet format (usually abbreviated as CAP). In the Smartcard world this is called an executable load file (abbreviated as ELF). Each CAP file corresponds to a Java package and contains multiple classes of which some may extend the javacard.framework.Applet class (also referred as cardlets). The corresponding term for those cardlets in the Smartcard domain would be executable module (abbreviated as EM). Once a CAP file has been loaded each Cardlet can be instantiated, from then on it can be selected and respond to commands. Such a cardlet instance would be called application in the Smartcard lingo.
