Eclipse-Keyple, an Open Source API for Ticketing.

Get access to Keyple now  :

The Calypso security guarantees a high level of security of the transaction between a Portable Object (Card, Smartphone, USB key…) and the equipment of the service provider, terminal or portable device. This high level of security needs a certain level of expertise to be correctly implemented in the equipment. CNA manages a set of technical documents to support to the developers such as technical notes available on the Calypso standard technical support website.

The main scope of Keyple is to allow developers to develop applications that communicates with Calypso portable objects, without being obliged to develop all the Calypso layer, that requires a lot of investment and expertise and  big investments. So keyple is an abstraction layer that implement all the Calypso processing between a contactless secure element  and a secure module into a terminal.

The operating systems and cryptographic calculations processed in both portable objects and Secure Access Modules are out of scope of keyple as the ticketing data model and fare calculations applications  that will use the functions of keyple  to access Calypso portable objects.


Keyple is an open source library available both in Java & C++:

  • It is designed on a mutual Object-Oriented Model it is Compatible with any terminal architecture: mobile, embedded or server.
  • It is agnostic to the Calypso PO reader interface, it is usable either in an embedded terminal, a remote web service or mobile application and it supports the integration of local contacts or contactless readers, or remote readers and proposes a generic interface to be connected to specific reader drivers or to remote car channel solution.
  • It manages the advanced security features of Calypso with the possibility to add extensions to manage also non-Calypso smartcard.

Global architecture

The Calypso SDK is divided in two major layers:

  • The ‘Secure Element Proxy API’ which allows managing SE readers in a generic way.
  • The ‘Calypso Processing API’ which contains at least the full sets of commands for Calypso Portable Object and Security Module, and the macro commands to manage secure Calypso transactions. This module could also be extended with features to support the Triangle application.

Dedicated reader’s plugins have to be implemented in order to interface the SE Proxy API with the specific reader’s drivers.

Keyple global architecture

SE Proxy API


The SE Proxy API provides a common way to manage local or remote SE readers, providing a common interface to address NFC mobile environment or PC/SC compliant readers, or any proprietary drivers.

The PC/SC API provides basic functions to list and select compliant readers, to establish a connection, and to transfer APDU commands and get the corresponding responses, one by one.

The Smart Card IO API, used as PC/SC interface for J2SE application, provides a higher abstraction level by automatically managing 61XXh and 6CXXh warning status. In this case, the usage of the Get Response command is no longer required, ISO 7816-4 APDU command could be managed in the same way whatever the transmission protocol ISO 7816-3 T=0 or T=1, case 4 APDU commands are always processed as in contactless.

‘Case 4’ commands shall always be set with ’Le’ at 00h.

‘Case 2’ commands must not be set with a ‘Le’ value higher than the number of available bytes.

The Open Mobile API, defined to address SE in mobile environments, adds another step of abstraction with the automatic allocation of logical channels. In this case, the Select Application command is useless; a logical channel opening is requested for a specific AID, then API performs directly the selection for the first available or the specified logical channel. The class bytes of the coming APDU commands are automatically updated for the selected logical channel.

To simplify the management of logical channels with a SE, the SE Proxy API limits the establishment of only one logical channel at a time per SE.

  • A Calypso PO supports the selection of only one application at a time.
  • A CSM HSM plugin could emulate the presence of several CSM SE.

To optimize the interfacing with remote SE readers (PO or SAM):

  • The SE proxy API manages grouped APDU commands: in order to perform operations comprised of sets of APDU requests and get the corresponding set of APDU responses through a single call. It may still be possible to emulate an APDU by APDU sequential transaction by using commands groups containing a single APDU command.
  • A single SE reader call allows to specify at once the AID of the application to select (in order to open a specific logical channel if necessary), to transmit a group of APDU commands to play, and to define the final logical channel status after the receipt of the last APDU response of the group (in order to keep the channel open or to close it).

To support revision 1.0 and 2.4 POs in contacts T=0 mode, APDU commands’ information may declare if the ISO 7816-4 APDU is a case 4. If a case 4 response misses its data bytes, the SE plugin may send a Get Response command to retrieve the missing data.

Plugins’ rules:

Ø  On a request to transmit a set of APDU commands to a specific SE Application, the SE plugin or its lower driver must open a logical channel and select the targeted application (if not already selected) without expecting an explicit SelectApplication command from the SE Proxy.

Ø  Only a single logical channel could be open at a time with a SE Reader.

Ø  For a communication with PO or CSM in contacts modes, on a request of case 4 APDU commands, the SE plugin may recover automatically the corresponding responses’ data, without expecting explicit GetResponse commands from the SE Proxy.

Ø  Case 4 APDU commands must be flagged and defined with Le at 00h by the SE Proxy.

Readers’ specific settings (e.g. contactless protocol sequences polling, communication speed…) may be managed at the plugin level. The SE proxy API provides a generic way to push or get specific reader’s parameters.

On a terminal, the SE Proxy API could be interfaced with several plugins at a time, in order to address PO and CSM, to operate both local and remote readers, supporting both PC/SC and proprietary readers

Calypso Processing APIs

Low level – PO & CSM commands’ sets APIs

The aim of the commands module is to be defined the APDU commands’ sets for PO & CSM. All these commands could be operated independently in standalone.

To manage PO & CSM APDU command, the library requires:

  • functions to build APDU requests in order to generate the arrays of bytes to send to a SE in a APDU requests’ group,
  • functions to parse the arrays of bytes replied by the SE in a APDU responses’ group.

High level – Secure Transaction APIs

The high level Calypso transaction module is defined on top of the PO & CSM commands’ API. The aim of this transaction module is to automate security operations linked to a session or a transaction. Through this layer of API, an application doesn’t require to manage directly CSM operations (like proposed by lots of contactless readers which embed CSM slots).

Distributed architecture

In a distributed architecture, the ticketing system is split between local lightweight terminals operating a Calypso PO, and a centralized ABT (Account Based Ticketing) server managing the SAM security. The distributed architecture is a simple evolution of the local architecture which is split in two parts:

  • the “Local Lightweight Ticketing Client” which operates the “Graphical User Interface” and the “Calypso PO Reader” management,
  • the “Remote ABT server” which centralizes the “ Customer Data Base” (access rights & registrated PO), the “Ticketing Processing” (PO authentication & update) and the “Calypso SAM Reader” Management.

A “Ticketing Client” requests the “ABT Server” for ticketing operations; there could be several Ticketing Clients at a time requesting the ABT Server (necessarily for different Calypso POs). The ABT Server could integrate several Calypso SAMs in order to satisfy several Ticketing Client sessions at a time. Cards or SAM’s commands are grouped to limit network exchanges for mobile, embedded terminal or server solution.

As presented on the figure below, can be found:

  • On the server side, as same as for a local architecture:
    • the “Calypso SDK” and
    • the “Plugins” (the remote SE Plugins & the Smart Card IO Plugin).

But in addition, the “virtual SE Master Service is defined”: it’s a web client on which the “Remote SE Plugin” is built; it drives a remote “Native SE Slave Service” as through a “bridge”.

  • On the client side, as same as for a local architecture:
    • Plugins are defined (the “NFC Reader Plugin” for the Android environment, or the “Smart Card IO Plugin for a java PC environment).
    • The “Calypso SDK” is also present but only its lowest layer is involved, the “SE Proxy API”.

A “Native SE Server Service” is added this service called by a “Remote SE Plugin” works on top a local “SE Proxy API”, it follows the remote ApduRequest requests from the SE bridge. Several ticketing sessions can be managed in parallel. The number of ticketing sessions that can be operated by the server at a time is restricted by the number connected Calypso SAM.

  • In case there is no SAM available, a new ticketing session is put on hold until the release of a SAM.
  • During a ticketing session (between a Ticketing Client and a ABT Server) a SAM can be allocated only for the duration of an operated Calypso secure session.



Get access to Keyple now  :