Java Card

This page explains how Fidesmo exposes the Java Card functionality provided by the Fidesmo Card. Java Card is a software technology that enables a developer to write programs that use the processor of the Fidesmo Card. A Java Card application is in the rest of this chapter referred to as a Cardlet. For the impatient reader there is a tutorial to get started developing for the Fidesmo Card.

The Fidesmo Card security architecture

The Fidesmo Card implements 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 Fidesmo Card receive a Security Domain (SD) of their own. This means that all service providers’ applications and data on the Fidesmo Card are sandboxed: No service provider can access other service provider's applications nor data.

The Fidesmo Card security architetcure

The RESTful API

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 Fidesmo Card.

CAP file management

In order to install a cardlet on a Fidesmo Card it must be uploaded to the Fidesmo backend first. The uploaded cardlet can then later be installed on any number of cards. 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.

Managing applications on the card

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 Fidesmo Card. 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.

Gradle plugins

In order to facilitate the development process Fidesmo has developed two gradle plugins. The first one, gradle-javacard, uses the JavaCard SDK from Oracle to convert from Java bytecode to Java Card bytecode.

The second gradle plugin, gradle-fidesmo, utilises your Fidesmo account details to upload the resulting CAP-file to the Fidesmo backend and it can then also install it on a Fidesmo Card via your local contactless reader.

We have published an example project in Github that integrates both plugins into the Java Card build process.

Overview of the Fidesmo gradle build

AID

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.

AID format exceptions

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

Memory management

Due to the special characteristics of the smartcard environment, it is necessary to follow these guidelines when developing Java Card software:

  • Allocate all memory in the 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.
  • To promote reuse, objects should remain in scope or referenced for the life of the applet, and their state (values of member variables) reset as appropriate before reuse.
  • Do not call the garbage collector JCSystem.requestObjectDeletion(). It might be interrupted by a power loss, damaging the card.

Cardlet compatibility

In order to run on the current Fidesmo Cards and to be portable to future revisions, your applet needs to follow these guidelines:

  • comply to Java Card 2.2.2 or 3.0.1 Classic
  • comply to GlobalPlatform 2.1.1
  • restrict your API usage to the standard Java Card and GlobalPlatform APIs
  • limit transaction to consume not more than 512 bytes of memory
  • never spawn more than 127 instances of you cardlet on one card
  • restrict your CAP file size to 64 kb
  • use only the following crypto algorithms
    • ALG_AES_BLOCK_128_CBC_NOPAD (128 / 192 / 256 bit keys)
    • ALG_DES_CBC_ISO9797_M1 (112 / 168 bit keys)
    • ALG_DES_CBC_ISO9797_M2
    • ALG_DES_CBC_NOPAD
    • ALG_RSA_NOPAD (2048 bit keys)
    • ALG_RSA_SHA_PKCS1
    • ALG_RSA_SHA_PKCS1_PSS
    • ALG_RSA_SHA_224_PKCS1_PSS
    • ALG_RSA_SHA_256_PKCS1_PSS
    • others only after request

The Terminology

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.