Keyple Calypso

Version 1.0 of the documentation is no longer actively maintained. The site that you are currently viewing is an archived snapshot. For up-to-date documentation, see the latest version.

Features / packages and corresponding usages

The Calypso transaction API provides a high-level of abstraction to define functional commands to manage a secure session with a Calypso Portable Object, to update or authenticate its data.

The transaction API is defined on a low-level Calypso commands API which contains the builders of PO and SAM APDU commands, and the corresponding parsers of APDU responses. This internal library is deprecated, and will be refactorized for the version 2.0.0 of Keyple Calypso.

org.eclipse.keyple.calypso.transactionhighCalypso Portable Object commands and secure transaction management
  • CalypsoAPI, command’s settings are limited to functional parameters
  • Calypso SAM (Secure Module) operations automatically processed
(only functional parameters)
lowCalypso PO & SAM APDU commands' sets
  • APDU command builders
  • APDU response parsers
(technical parameter settings specific to the PO & SAM revisions)

Ticketing terminal applications must import only the high-level Calypso transaction package.

Calypso packages
Calypso packages

Calypso Portable Object Selection

Compared to the generic Card Selection API (cf., a PO Selector could be defined to accept only non-invalidated Portable Object (in this cas an invalidated PO isn’t selected).

In addition, a PO Selection Request provides methods:

  • to prepare Select File command (useful in particular to manage REV1 Calypso PO for which the select of the targeted DF is required).
  • and to prepare simple read record command (useful to optimize the read of a file present on all targeted PO).

The matching SmartCard resulting from a PO Selection Request is a Calypso PO. In case file records have been read during the selection: the corresponding data could be recovered in the Calypso PO card image.

Calypso Selection v1.0.0
Calypso Selection v1.0.0

Calypso Portable Object Transaction

A Card Resource is a set of a Reader and a selected Card application.

  • A Calypso Portable Object is the image of a selected Calypso PO.
  • A Calypso SAM is the image of a selected Calypso SAM.

To operate a Calypso transaction:

  • At least a Calypso Resource (CardResource<CalypsoPo>) is required.
  • A SAM Resource ((CardResource<CalypsoSam>) is required too if security features are involved (Calypso secure session, Stored value transaction, PIN encryption, etc…).

A Calypso PO image provides public getters in order to recover the information of the selected PO (startup data, file data, … etc).

A transaction with a Calypso PO is fully managed through the PoTransaction object:

  • First a set of PO commands could be defined through prepare commands.
  • Next the prepared PO commands transmitted when operating a process command.
  • The responses of the PO are then recovered through the Calypso PO image.
Calypso API Global Architecture
Calypso API Global Architecture

Calypso card image

When read commands have been exchanged with a Calypso PO, the corresponding data could be recovered by parsing the file structure of the PO card image.

Calypso PO card image
Calypso PO card image

Calypso transaction

Only the process methods generate communication with the Calypso PO and SAM.

  • processPoCommands is used to transmit a set of prepared PO commands (outside or inside a secure session).
  • processOpening issues an Open Secure Session followed by the prepared PO commands.
  • processClosing issues the last prepared PO commands and transmits a Close Secure Session.

The prepareReleaseChannel method allows to the logical channel with the Calypso PO at the end of the processing of the next process method.

Calypso transaction
Calypso transaction

Data model extension

Calypso Data Model
Calypso Data Model

Secure session sequence

Calypso session
Calypso session