Keyple Core Application API

version 0.9

Reader Access

On Keyple, the smart card readers are managed through plugins in order to integrate specific reader solutions. The ‘Secure Element Proxy Service’ singleton provides the unique name list of registered plugins. There can be three kinds of plugin:

A smart card reader is identified through its unique name in a plugin. There are two kinds of reader:

(The APDU transmission with a Secure Element is managed at the low-level SE Channel API.)

Specific Plugin

To hide plugin native implementation classes, the reader plugins are registered to the SE Proxy Service through related specific plugin factory. Specific Plugin v0.9

Reader Notifications

To be notified about ‘Plugin Event’ or ‘Reader Event’, a terminal application must implement the dedicated ‘Plugin Observer’ or ‘Reader Observer’ interfaces.

Reader Notifications v0.9.0

Plugin event

Several ‘Plugin Observers’ could be registered to an Observable Plugin. In case of reader connection / disconnection, the observable plugin notifies sequentially the registered observers with the corresponding plugin event. The observable plugin is a blocking API, the thread managing the issuance of the plugin event waits the acknowledge of the observer currently notified.

Reader event

Several ‘Reader Observers’ could be registered to an Observable Reader. In case of SE insertion / match / removal, the observable reader notifies sequentially the registered observers with the corresponding reader event. The observable reader could be a blocking API, the thread managing the issuance of the plugin event could wait the acknowledge of the notified observers.

An observable reader has the capability to be set with a ‘Default Selections Request’: in this case when a SE is inserted in the reader, the reader will try to operate the configured default selections. If a selection successfully matches with the SE, instead to simply notify the insertion of SE, the observable reader will notify about a successful selection with a SE application.

When the processing of an inserted or matched SE is finished, a reader observer must release the logical channel with the Secure Element, in order to prepare the observable reader to detect the removal of the SE.

Observable reader states

An observable reader is active only when at least one reader observer is registered, and if the start of the detection has been requested. When active, an observable read could switch between three internal states: ‘Wait for SE Insertion’, ‘Wait for SE Processing’, & ‘Wait for SE Removal’.

In the nominal case, a Reader Observer indicates to the observable reader that the processing of the SE is finished by releasing the SE Channel. To manage a failure of the reader observer process, the observable reader interface provides also a method to finalize the SE processing.

Observable Reader States

The states could be switched:

If a SE detection is started with the ‘repeating’ polling mode, then later when the SE is removed, the reader starts again to detect a SE.

Whatever the plugin of observable reader, when waiting for the SE removal, any observable reader shall have the capability to notify the remove of the SE. Some reader plugin solution could have the capability to notify a SE removal also during the processing of the SE.

SE Selection

Selection scenarios

Depending on the SE transaction use case, or on the reader capability, there are two ways to manage the selection of a SE:

Selection v0.9

Selection setting and processing

A SE Selection request is defined with a SE Selector. A SE Selector could be defined with tree optional levels of selection filter.

Depending on the Keyple SE extension library, a SE request could be completed with specific SE commands to operate at the selection (for example, a Select File for a specific DF LID, the read of a specific file).

For terminal managing several kinds of SE applications, a SE Selection could be prepared with several SE selection request to operate sequentially with the SE.

According to the defined ‘multi SE request processing’ mode, the SE selection could stop at the first selection request matching SE application, otherwise all the prepared SE selection request could be operated.

SE Selection v0.9

The result of a SE request selection is a card image of a matching SE. For a SE selection with multiple requests, several matching SE could be provided.