Upgrade from an earlier version of Keyple

This guide is intended to help a user of a previous version of Keyple Java to upgrade his application to a new version of the library.

Upgrade from:

2.+ to 3.+
1.+ to 2.+

Upgrade from “2.+” to “3.+”

This major release follows the adoption of Keypop APIs in place of CNA Terminal APIs.

We recommend that you follow the steps below in the order suggested:

Update the project dependencies management
Perform a global text search & replace across the entire project
Apply the changes to the card/SAM selection manager
Apply the changes to the card transaction manager
Apply the changes to the signatures management (PSO or basic) during card transactions
Apply the changes to the SAM resource service

All deprecated methods have been removed. If your project contains such methods, please check the changelogs for replacement methods.

Dependencies management

Replace the legacy Keyple dependencies with the latest versions. To do this, use the configuration wizard to correctly import the new artifacts into your project.

Renaming

Search and replace (in “case-sensitive” and “whole-word” mode) in the following order the following strings when present:

org.calypsonet.terminal.calypso => org.eclipse.keypop.calypso.card
org.calypsonet.terminal => org.eclipse.keypop
card.sam => crypto.legacysam.sam
Reader => CardReader
ObservableReader => ObservableCardReader
ReaderEvent => CardCardReader
CalypsoSam => LegacySam
CardSelection => CardSelectionExtension
CalypsoApiProperties => CalypsoCardApiProperties
SamIOException => CryptoIOException
CalypsoCardSelection => CalypsoCardSelectionExtension
GenericCardSelection => GenericCardSelectionExtension
CardSecuritySetting => SymmetricCryptoSecuritySetting
createCardSecuritySetting => createSymmetricCryptoSecuritySetting
processCommands(true) => processCommands(ChannelControl.CLOSE_AFTER)
processCommands(false) => processCommands(ChannelControl.KEEP_OPEN)
processApdusToByteArrays(true) => processApdusToByteArrays(ChannelControl.CLOSE_AFTER)
processApdusToByteArrays(false) => processApdusToByteArrays(ChannelControl.KEEP_OPEN)
processApdusToHexStrings(true) => processApdusToHexStrings(ChannelControl.CLOSE_AFTER)
processApdusToHexStrings(false) => processApdusToHexStrings(ChannelControl.KEEP_OPEN)
createCardSelectionManager() => getReaderApiFactory().createCardSelectionManager()
createCardSelection() =>
- Calypso card extension: getCalypsoCardApiFactory().createCalypsoCardSelectionExtension()
- Generic card extension: createGenericCardSelectionExtension()
createCardTransactionWithoutSecurity => getCalypsoCardApiFactory().createFreeTransactionManager
createSearchCommandData => getCalypsoCardApiFactory().createSearchCommandData
prepareComputeSignature => getCryptoExtension(CardTransactionLegacySamExtension.class).prepareComputeSignature
prepareVerifySignature => getCryptoExtension(CardTransactionLegacySamExtension.class).prepareVerifySignature

Card selection

Prepare a Calypso card selection case

CalypsoCardSelection calypsoCardSelection = 
    CalypsoExtensionService.getInstance().createCardSelection()
        .filterByDfName(...)
        .setFileOccurrence(...)
        .setFileControlInformation(...);

cardSelectionManager.prepareSelection(calypsoCardSelection);

IsoCardSelector isoCardSelector =
    SmartCardServiceProvider.getService().getReaderApiFactory().createIsoCardSelector()
        .filterByDfName(...)
        .setFileOccurrence(...)
        .setFileControlInformation(...);

CalypsoCardSelectionExtension calypsoCardSelectionExtension =
    CalypsoExtensionService.getInstance().getCalypsoCardApiFactory().createCalypsoCardSelectionExtension();

cardSelectionManager.prepareSelection(isoCardSelector, calypsoCardSelectionExtension);

Prepare a Calypso SAM selection case

CalypsoSamSelection CalypsoSamSelection = 
    CalypsoExtensionService.getInstance().createSamSelection()
        .filterByProductType(productType)
        .filterBySerialNumber(serialNumber);

cardSelectionManager.prepareSelection(CalypsoSamSelection);

String powerOnDataFilter = LegacySamUtil.buildPowerOnDataFilter(productType, serialNumber);

BasicCardSelector basicCardSelector =
    SmartCardServiceProvider.getService().getReaderApiFactory().createBasicCardSelector()
        .filterByPowerOnData(powerOnDataFilter);

LegacySamSelectionExtension legacySamSelectionExtension =
    LegacySamExtensionService.getInstance().getLegacySamApiFactory().createLegacySamSelectionExtension();

cardSelectionManager.prepareSelection(basicCardSelector, legacySamSelectionExtension);

Prepare a Generic card selection case

GenericCardSelection genericCardSelection =
    GenericExtensionService.getInstance().createCardSelection()
        .filterByDfName(...)
        .setFileOccurrence(...)
        .setFileControlInformation(...);

cardSelectionManager.prepareSelection(genericCardSelection);

IsoCardSelector isoCardSelector =
    SmartCardServiceProvider.getService().getReaderApiFactory().createIsoCardSelector()
        .filterByDfName(...)
        .setFileOccurrence(...)
        .setFileControlInformation(...);

GenericCardSelectionExtension genericCardSelectionExtension =
    GenericExtensionService.getInstance().createGenericCardSelectionExtension();

cardSelectionManager.prepareSelection(isoCardSelector, genericCardSelectionExtension);

Schedule a card selection scenario

cardSelectionManager.scheduleCardSelectionScenario(
    observableCardReader,
    detectionMode,
    notificationMode);

cardSelectionManager.scheduleCardSelectionScenario(
    observableCardReader,
    notificationMode);

Card Transaction

Create a card transaction manager without security

CardTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance()
        .createCardTransactionWithoutSecurity(cardReader, card);

FreeTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance()
        .getCalypsoCardApiFactory().createFreeTransactionManager(cardReader, card);

Create a card transaction manager with security (regular mode)

CardSecuritySetting securitySetting =
    CalypsoExtensionService.getInstance().createCardSecuritySetting()
        .setControlSamResource(samReader, sam);

CardTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance()
        .createCardTransaction(cardReader, card, securitySetting)

SymmetricCryptoCardTransactionManagerFactory cryptoCardTransactionManagerFactory =
    LegacySamExtensionService.getInstance().getLegacySamApiFactory()
        .createSymmetricCryptoCardTransactionManagerFactory(samReader, sam);

SymmetricCryptoSecuritySetting securitySetting =
    CalypsoExtensionService.getInstance().getCalypsoCardApiFactory()
        .createSymmetricCryptoSecuritySetting(cryptoCardTransactionManagerFactory);

SecureRegularModeTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance().getCalypsoCardApiFactory()
        .createSecureRegularModeTransactionManager(cardReader, card, securitySetting);

Create a card transaction manager with security (extended mode)

CardSecuritySetting securitySetting =
    CalypsoExtensionService.getInstance().createCardSecuritySetting()
        .setControlSamResource(samReader, sam);

CardTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance()
        .createCardTransaction(cardReader, card, securitySetting)

SymmetricCryptoCardTransactionManagerFactory cryptoCardTransactionManagerFactory =
    LegacySamExtensionService.getInstance().getLegacySamApiFactory()
        .createSymmetricCryptoCardTransactionManagerFactory(samReader, sam);

SymmetricCryptoSecuritySetting securitySetting =
    CalypsoExtensionService.getInstance().getCalypsoCardApiFactory()
        .createSymmetricCryptoSecuritySetting(cryptoCardTransactionManagerFactory);

SecureExtendedModeTransactionManager cardTransactionManager =
    CalypsoExtensionService.getInstance().getCalypsoCardApiFactory()
        .createSecureExtendedModeTransactionManager(cardReader, card, securitySetting);

PSO signature management (computation/verification)

TraceableSignatureComputationData signatureComputationData =
    CalypsoExtensionService.getInstance()
        .createTraceableSignatureComputationData();

cardTransactionManager.prepareComputeSignature(signatureComputationData);

TraceableSignatureComputationData signatureComputationData =
    LegacySamExtensionService.getInstance()
        .getLegacySamApiFactory().createTraceableSignatureComputationData();

cardTransactionManager.getCryptoExtension(CardTransactionLegacySamExtension.class)
    .prepareComputeSignature(signatureComputationData);

SAM resource service

CardResourceProfileExtension samResourceProfileExtension =
    CalypsoExtensionService.getInstance()
        .createSamResourceProfileExtension(
            CalypsoExtensionService.getInstance()
                .createSamSelection()
                .filterByProductType(CalypsoSam.ProductType.SAM_C1));

CardResourceProfileExtension samResourceProfileExtension =
    LegacySamExtensionService.getInstance()
        .createLegacySamResourceProfileExtension(
            LegacySamExtensionService.getInstance()
                .getLegacySamApiFactory()
                .createLegacySamSelectionExtension(),
            LegacySamUtil.buildPowerOnDataFilter(LegacySam.ProductType.SAM_C1, null));

Miscellaneous

Contact reader payload capacity management

ContextSetting contextSetting = 
    CalypsoExtensionService.getInstance().getContextSetting().setContactReaderPayloadCapacity(...);

ContextSetting contextSetting = 
    LegacySamExtensionService.getInstance().getContextSetting().setContactReaderPayloadCapacity(...);

Upgrade from “1.+” to “2.+”

Here is a comparative review of the main API changes between Keyple 1.+ and 2.+:

Dependency management

Use the configuration wizard to correctly import the new artifacts into your project.

Initial configuration

Use of a provider to access the smart card service

SmartCardService smartCardService = SmartCardService.getInstance();

SmartCardService smartCardService = SmartCardServiceProvider.getService();

Use of builders to instantiate plugin factories

Plugin plugin = smartCardService.registerPlugin(new PcscPluginFactory(null, new ExceptionHandlerImpl()));
...
((ObservableReader) reader).addObserver(new CardReaderObserver());

Plugin plugin = smartCardService.registerPlugin(PcscPluginFactoryBuilder.builder().build());
...
((ObservableCardReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableCardReader) reader).addObserver(new CardReaderObserver());

Exception handlers are no longer required when registering the plugin but only when starting the observation.

Use of a new interface dedicated to the management of protocols

reader.activateProtocol(
    PcscSupportedContactlessProtocols.ISO_14443_4.name(), 
    ContactlessCardCommonProtocols.ISO_14443_4.name());

((ConfigurableCardReader) reader).activateProtocol(
    PcscSupportedContactlessProtocols.ISO_14443_4.name(), 
    CARD_ISO_14443_4);

Use of plugin and reader extensions for specific configurations

The examples below show the evolutions for the configuration of a PC/SC reader but the principle is the same for all plugins and readers.

reader
    .setContactless(true)
    .setIsoProtocol(PcscReader.IsoProtocol.T1);

plugin.getReaderExtension(PcscReader.class, reader.getName())
    .setContactless(true)
    .setIsoProtocol(PcscReader.IsoProtocol.T1);

Card selection

Use a manager instead of service for card selection

CardSelectionsService cardSelectionsService = new CardSelectionsService();

CardSelectionManager cardSelectionManager = smartCardService.createCardSelectionManager();

A new instance of the card selection manager is provided by the smart card service.

Use of a card extension to create a card selection

GenericCardSelectionRequest genericCardSelectionRequest =
    new GenericCardSelectionRequest(
        CardSelector.builder()
            .aidSelector(CardSelector.AidSelector.builder().aidToSelect(cardAid).build())
            .build());

CardSelection cardSelection = GenericExtensionService.getInstance()
    .createCardSelection()
    .filterByDfName(cardAid);

The CardSelector class does not exist anymore.
A generic card extension is now available.
The card extension service is used to configure the card selection.

Explicit card selection

CardSelectionsResult selectionResult = cardSelectionsService.processExplicitSelections(reader);

CardSelectionResult selectionResult = cardSelectionManager.processCardSelectionScenario(reader);

Note the removal of the “s” in CardSelectionResult.

Scheduled card selection

((ObservableReader) reader)
    .setDefaultSelectionRequest(
        defaultSelectionsRequest,
        ObservableReader.NotificationMode.MATCHED_ONLY,
        ObservableReader.PollingMode.REPEATING);
((ObservableReader) reader).addObserver(new CardReaderObserver());

cardSelectionManager.scheduleCardSelectionScenario(
    (ObservableCardReader) reader,
    ObservableCardReader.DetectionMode.REPEATING,
    ObservableCardReader.NotificationMode.MATCHED_ONLY);
((ObservableCardReader) reader).setReaderObservationExceptionHandler(new ExceptionHandlerImpl());
((ObservableCardReader) reader).addObserver(new CardReaderObserver());

The selection data is no longer provided to the observable reader but to the selection manager. It is the observable reader that is provided to the selection manager.

The processing of the result of the selection response has changed

AbstractSmartCard smartCard =
  defaultSelection
      .processDefaultSelectionsResponse(event.getDefaultSelectionsResponse())
      .getActiveSmartCard();

SmartCard smartCard =
    cardSelectionManager
        .parseScheduledCardSelectionsResponse(event.getScheduledCardSelectionsResponse())
        .getActiveSmartCard();

AbstractSmartCard was changed to the SmartCard interface.

Calypso Card Extension

Vocabulary

PO has been replaced by Card.

SAM management

The SAM resource manager has been replaced by a generic Card Resource Service.

Card transaction

Access to the card transaction manager has changed. It is now done through the card extension service.

PoTransaction poTransaction =
    new PoTransaction(
        new CardResource<CalypsoPo>(poReader, calypsoPo),
        CalypsoUtils.getSecuritySettings(samResource));

CardTransactionManager transactionManager = CalypsoExtensionService.getInstance()
    .createCardTransaction(cardReader, calypsoCard, cardSecuritySetting);

Distributed systems

Remote plugin registration

// Init the remote plugin factory.
RemotePluginServerFactory factory =
    RemotePluginServerFactory.builder()
        .withDefaultPluginName()
        .withSyncNode()
        .withPluginObserver(new RemotePluginServerObserver())
        .usingEventNotificationPool(
            Executors.newCachedThreadPool(r -> new Thread(r, "server-pool")))
        .build();

// Register the remote plugin to the smart card service using the factory.
SmartCardService.getInstance().registerPlugin(factory);

RemotePluginServerFactory factory =
    RemotePluginServerFactoryBuilder.builder(REMOTE_PLUGIN_NAME)
        .withSyncNode()
        .build();

// Register the remote plugin to the smart card service using the factory.
ObservablePlugin plugin =
    (ObservablePlugin) SmartCardServiceProvider.getService().registerPlugin(factory);

// Init the remote plugin observer.
plugin.setPluginObservationExceptionHandler(new ExceptionHandlerImpl());
plugin.addObserver(new RemotePluginServerObserver());

You have to specify the name of the plugin.
It is no longer necessary to provide a thread pool.
The exception handler must be provided as for any observable plugin before adding an observer.

Local service registration

// Init the local service using the associated factory.
LocalServiceClientFactory.builder()
    .withDefaultServiceName()
    .withSyncNode(endpointClient)
    .withoutReaderObservation()
    .getService();

// Init the local service factory.
LocalServiceClientFactory factory =
    LocalServiceClientFactoryBuilder.builder(LOCAL_SERVICE_NAME)
        .withSyncNode(endpointClient)
        .build();

// Init the local service using the associated factory.
SmartCardServiceProvider.getService().registerDistributedLocalService(factory);

You have to specify the name of the local service.
The local service must be registered with the smart card service.
It behaves like a plugin or reader and also provides an extension to access specific settings.