tdassonville / keyple-java

Keyple Java source

'Eclipse Keyple' Java implementation

This is the repository for the Java implementation of the 'Eclipse Keyple' API. (In September 2019, the C++ implementation will be hosted on https://github.com/eclipse/keyple-cpp)

Global Architecture of Keyple

The API is currently divided in two major layers:

• The ‘Keyple Core' : a Secure Element Proxy API which allows managing SE readers in a generic way, whaterver the reader driver or environment, and for standalone or distributed solution.
• A ‘Calypso Keyple extension' : a high level Calypso Processing API allowing to operate commands with a Calypso Portable Object, and to manage a secure Calypso transaction. Dedicated reader’s plugins have to be implemented in order to interface the SE Proxy API with the specific reader’s drivers.

Supported platforms

• Java SE 1.6 compact2
• Android 4.4 KitKat API level 19

keyple-java repositories structure

• Modules that are provided as artifacts
  • keyple-core: source and unit tests for the SE Proxy module.
  • keyple-calypso: source and unit tests for the Calypso library.
  • keyple-plugin: source and unit tests for the different plugins: smartcard.io PC/SC, Stub, Android NFC, Android OMAPI, etc.
• developer support, testing
  • example: source for Keyple implementation examples, generic or Calypso specific.
  • integration: source for the integration code (SDK).

Keyple features and corresponding packages

Keyple features global for any Secure Element solution:

Features	Packages
Selections of Secure Elements (high level API)	org.eclipse.keyple.core.selection
Management of SE readers	org.eclipse.keyple.core.seproxy
Notifications of reader plug/unplug, of SE insertion/remove definition of automatic selection request in case of SE insertion on an Observable Reader.	org.eclipse.keyple.core.seproxy.event
Communication protocols filters (setting for contactless/contacts SE Reader)	org.eclipse.keyple.core.seproxy.protocol
Reader plugins implementation support Utility classes providing generic processing for SE Reader Plugins	org.eclipse.keyple.core.seproxy.plugin
Transmition of grouped APDU commands to a SE Reader (low level API)	org.eclipse.keyple.core.seproxy.message
SE specific library implementation support generic API to build a SE specific commands library	org.eclipse.keyple.core.command

Keyple features defined to support the Calypso solution:

Features	Packages
Calypso Portable Object commands and secure transaction management high level CalypsoAPI, commands’ settings are limited to functional parameters Calypso SAM (Secure Module) operations automatically processed	org.eclipse.keyple.calypso.transaction
Calypso PO responses data parsing	org.eclipse.keyple.calypso.command.po.parser
Calypso SAM responses data parsing	org.eclipse.keyple.calypso.command.sam.parser
Calypso PO & SAM commands' sets low level Calypso API, commands’ settings include technical parameters specific to Calypso PO revisions or Calypso SAM revisions	org.eclipse.keyple.calypso.command org.eclipse.keyple.calypso.command.po org.eclipse.keyple.calypso.command.po.builder org.eclipse.keyple.calypso.command.po.parser.session org.eclipse.keyple.calypso.command.sam.parser.session org.eclipse.keyple.calypso.command.sam.builder org.eclipse.keyple.calypso.command.sam

Keyple packages and corresponding usages

Depending on the targetting usage: implementation of a ticketing application (blue circle), a reader plugin (red circle), or a SE library (green circle), only specific Keyple packages must be imported.

• generic packages for any SE solution

• specific packages for Calypso

JARs

The Eclipse Keyple Java artifacts are published on the Eclipse Keyple Project page [https://projects.eclipse.org/projects/iot.keyple/downloads] (may be soon also available on Maven).

• Keyple modules:
  • 'Keyple Core module' JAR: the generic API to manage Secure Element Readers and to select SE application.
  • 'Keyple Calypso Library JAR': the Calypso API to operate a transaction with a Calypso Portable Object.
• Keyple plugins:
  • 'Keyple PC/SC plugin JAR': to manage PC/SC readers on a PC environment supporting the # javax.smartcardio API
  • 'Keyple NFC Android plugin AAR': to operate the contactless reader of an Android Environment supporting the android.nfc API
  • 'Keyple OMAPI Android plugin AAR': to operate the internal contacts readers of an Android Environment supporting the OMAPI
  • 'Keyple "stub" plugin JAR': plugin to simulate the presence of fake readers with or without fake cards
  • 'Keyple "Remote SE" plugin JARs': plugin & service to manage a SE remotely in a transparent way.

Documentation

The current functional specification keyple-doc is obsolete.

Building the examples and the Keyple components

Java components

Prerequisites

Here are the prerequisites to build the keyple components (jars) and to run the /example projects

• Java JDK 1.6 or newer
• Maven (any version) available here

Linux or Macos

Following command will build all the artifacts at once.

./gradlew build  --info

Windows

Following command will build all the artifacts at once.

.\gradlew.bat build  --info

Android components

If you want to build the keyple android components (aar plugins, apk example app), you need :

• Java JDK 1.8 or newer (OMAPI app requires java 1.8)
• Intellij 2018 community version or Android Studio 3.0
• Android sdk 26 should be installed on your machine follow those instructions

To acknowledge where is installed you Android SDK, you need to create a file local.properties in the /android, /android/example/calypso/nfc, /android/example/calypso/omapi folders with the following content sdk.dir=absolut/path/to/where/your/android/sdk/is

For instance sdk.dir=/Users/user/Library/Android/sdk

Linux or Macos

To build the plugins, execute the following commands in the /keyple-java folder.

./gradlew -b ./android/build.gradle build

To build the example app NFC and OMAPI

./gradlew -b ./android/example/calypso/nfc/build.gradle assembleDebug
./gradlew -b ./android/example/calypso/omapi/build.gradle assembleDebug

Windows

To build the plugins, execute the following commands in the /keyple-java folder

.\gradlew.bat -b ./android/build.gradle build

To build the example app NFC and OMAPI

.\gradlew.bat -b ./android/example/calypso/nfc/build.gradle assembleDebug
.\gradlew.bat -b ./android/example/calypso/omapi/build.gradle assembleDebug