Interoperability & compliance of Keyple-based ticketing terminal solutions

In order to guarantee interoperability between smart cards and terminals, the ‘Calypso Networks Association’ (CNA) encourages ticketing operators to follow various specifications and certification processes.

Contactless reader communication protocol

For compliance with the contactless reader communication protocol, CNA supports the certification programme standardised by the ‘Smart Ticketing Alliance’ (STA) for ‘Public Transport Readers’ (PT Readers). Several test laboratories are approved for ‘Proximity Coupling Device’ (PCD) certification under the supervision of the ‘Certification Body’ Paycert.

Separation and functional logic of the various software layers

To guarantee the functional capability of the ticketing terminals, CNA has proposed a software architecture with a distribution of responsibilities per layer, and has defined dedicated functional requirements for each software layer.

Variations of Keyple libraries sets

Different sets of Keyple libraries are available depending on the programming language: Java or C++.

For the reader and Calypso software layers, Keyple maintenance is performed for the last two generations of libraries:

• the nominal branch (the most recent) based on Eclipse Keypop terminal APIs, for which upgrades and fixes are actively produced: Service & Calypso Card Keyple libraries with a major version number greater than or equal to 3.0.0.
• and the legacy branch based on CNA terminal APIs, for which only patches continue to be supplied: Service & Calypso Card Keyple libraries with a major version number between 2.0.0 and 3.0.0 (Keyple libraries prior to 2.0.0 are archived).

Further, Keyple’s Calypso libraries’ features have also been regularly enhanced: first Prime Regular, then Extended and PKI. Command injection countermeasures have also moved from a permissive to a stricter implementation.

Reader software layer

For terminals integrating contactless and/or contact readers, the Keyple’s ‘Core’ libraries have been designed to meet the terminal requirements for the reader layer.

• In order to declare that a configuration of Keyple Core libraries and a smart card reader plugin are indeed compliant with the terminal requirements for the reader layer, the main condition is that the plugin used to interface the reader has been implemented according to the Keyple plugin development guide.

The Keyple project hosts plugins for interfacing reader solutions based on standardized APIs: PC/SC and Android NFC. Pending the future certification programme for reader layer libraries, CNA plans to publish the self-declarations of conformity of the Keyple Core libraries for reader solutions interfaced with these plugins:

• Keyple Java Service with PC/SC plugin set
• Keyple Java Service with Android NFC plugin set
• Keyple Legacy Java Service with PC/SC plugin set
• Keyple Legacy Java Service with Android NFC plugin set
• Keyple C++ Service with PC/SC plugin set

Properties of PC/SC and NFC reader solutions

Terminal requirements support declarations

For “contactless” readers, the ‘RL-CL-RFSTA.2’ rule defines the need for the product’s RF properties to be certified according to the scheme defined by the STA. This RF certification of a smart card reader is under the manufacturer’s responsibility.

• All NFC readers are “self-declared” by NFC reader manufacturers as compliant with the NFC Forum. This NFC declaration is recognized by the STA and thus implicitly considered as compliant with STA certification.
• Most of PC/SC contactless readers are by default not STA-certified.

For reader solutions with the ‘Selection’ applicability, rules regulate “DF Name” processing.

• For legacy library sets, these rules are respected, but the API used to set the DF Name to be selected was then accessed at the Calypso layer, instead of the reader layer.
• Nominal versions of library sets correctly handle DF Name settings at the reader layer.

Except for RF certification and ‘DF Name’ selection rules, all other terminal requirements defined by CNA for the reader layer, applicable according to the properties of the PC/SC or NFC reader solutions, are fully supported by default.

All other reader layer requirements are fully supported if the reader plugin is developed in accordance with the development guide.

‘Keyple Java Service sets’ definitions for PC/SC & Android NFC plugins (still updated)

‘Keyple Legacy Java Service sets’ definitions for PC/SC & Android NFC plugins (still fixed)

‘Keyple Legacy C++ Service set’ definition for PC/SC plugin (still fixed)

Calypso software layer

The Keyple’s ‘Calypso’ libraries have also been implemented to meet the terminal requirements for the Calypso layer, regardless of the reader solutions used. 2 conditions must be met to guarantee « complete » compliance with the requirements of the Calypso layer:

• the versions of Keyple’s Calypso libraries must be compliant with versions 2.0 or higher of the terminal Calypso APIs,
• & the reader software layer used as a basis (Keyple’s ‘Core’ libraries + reader plugins) must comply with the terminal requirements for the reader layer.

Pending the future certification programme for Calypso layer libraries, CNA has published the self-declarations of conformity of the Keyple Calypso libraries (independently of interfaced reader solutions, but on the basis of a compliant reader software layer):

• Keyple Java Calypso Prime PKI set 2
• Keyple Java Calypso Prime PKI set
• Keyple Java Calypso Prime Extended set
• Keyple Legacy Java Calypso Prime Extended set 2
• Keyple Legacy Java Calypso Prime Extended set
• Keyple Legacy Java Calypso Prime Regular set
• Keyple Legacy C++ Calypso Prime Regular set 2
• Keyple Legacy C++ Calypso Prime Regular set

Terminal requirements support declarations

For the various Keyple Calypso library sets, all applicabilities and terminal requirements are supported, except for those listed in the table below.

• For requirements for which support is conditional on the availability of specific features, support has been integrated at the same time as the addition of the corresponding feature.
• Prior to the integration of Eclipse Keypop, Keyple libraries were based on terminal APIs implemented and published by CNA: the Keyple libraries sets corresponding to these old configurations contain the word “legacy” in their name.

For older configurations, the ‘CL-CSS-RESPLE.1’ requirement, the countermeasure was initially implemented in a ‘permissive’ way, requiring applications to set only card commands for which the response size can be predetermined. More recent configurations benefit from a more ‘strict’ implementation of the countermeasure, which is compliant regardless of the processing set at application level as indicated in the Calypso development guide.

The lack of official support for the “HCE” functionality and the related ‘CL-SEL-SNHEADER.2’ requirement is not a limitation to correctly processing Calypso HCE solutions, as the HCE token data can still be recovered as described in the Calypso development guide.

About the ‘CL-PERF-HFLOW.1’ requirement, the Keyple Calypso libraries have been designed to optimize card & SAM command exchanges with the best possible performance, depending on the terminal architecture:

• for an embedded architecture (saving latencies of between 1 and 10 milliseconds on transmissions with local readers),
• for a distributed architecture (saving latencies of between 10 and 100 milliseconds on network exchanges with remote readers).

Concerning the ‘CL-CMD-GETPUT.1’ requirement, the “Get/Put Data” applicability support is limited to the management of the ‘Get Data’ command. The optional ‘Put Data’ command is not supported.

‘Keyple Java Calypso Prime PKI set 2’ definition (still updated)

‘Keyple Java Calypso Prime PKI set’ definition

‘Keyple Java Calypso Prime Extended set’ definition

‘Keyple Legacy Java Calypso Prime Extended set 2’ definition (still fixed)

‘Keyple Legacy Java Calypso Prime Extended set’ definition

‘Keyple Legacy Java Calypso Prime Regular set’ definition

‘Keyple Legacy C++ Calypso Prime Regular set 2’ definition (still fixed)

‘Keyple Legacy C++ Calypso Prime Regular set’ definition

Ticketing software layer

For a ticketing terminal solution built on the Keyple framework, the responsibility for complying with the requirements for the ticketing software layer lies exclusively with the developers of the terminal application using the ‘public’ Reader & Calypso terminal APIs.