SpringCore Common features Device selection

April 13, 2023 at 2:40 AM

SpringCore device selection

All SpringCore Tools need to communicate with a target SpringCore device.

They share the same parameters to list the available devices, and to specify the one the user wants.

The main parameter is the type of connection (physical link plus protocol), among

  • USB Direct
  • PC/SC, using SCardControl
  • PC/SC, using SCardTransmit,
  • UDP Direct,
  • TCP Direct,
  • Going through the SpringCard Companion Service

Using USB Direct

USB Direct is the default communication mode for all the SpringCore Tools. It relies on the fact that the device is connected through USB to the computer, and that the USB Direct interface is enabled, i.e.

  • The Disable USB and the Disable SpringCore direct as secondary USB interface bits are not set in the USB options register
  • The device is not currently connected by another medium (network, BLE, …).

USB Direct driver

The SpringCore USB Direct interfaces uses

  • The generic WinUSB driver for Windows computes, starting with Windows 10. Earlier versions are not supported.
  • The generic libusb direct access library for Linux and Mac OS X computers. Working with libusb is allowed only for the root user. Use sudo to run the SpringCore Tools as root.

List the USB Direct devices

SpringCoreTool.exe --list

Note: all the tools, not only SpringCoreTool.exe*, do produce the same output when invoked with the* --list parameter.

You may also show a few technical data regarding the devices and their connection parameters using --list-details instead of --list:

SpringCoreTool.exe --list-details

Select one of the USB Direct devices

If the --list command shows more than one device, use the --index=<INDEX> parameter to select the target device.

For instance, to show the data of the second device (index 1), use:

SpringCoreTool.exe infos --index=1

PC/SC

PC/SC is the de-facto standard for smartcard readers. The key advantage of connecting the SpringCore device through PC/SC is that the operation is medium-agnostic: the device could be connected through USB or network or whatever, the exchange will take place through the standard PC/SC API and stack without any adherence to the underlying communication link.

This is particularly useful for Linux and Mac OS X where PC/SC does not require a root access (at the difference with USB Direct).

To be able to use the SpringCore Tools through PC/SC, the following condition shall be met:

  • The Primary profile field shall be set to 02 (CCID) in the Profile register,
  • The device shall be activated by a PC/SC driver suitable for the computer.

PC/SC, using SCardControl

This communication method works only if the PC/SC driver allows SCardControl calls.

They are always allowed when SpringCard PC/SC drivers for Windows are used, but are disabled by default when the open-source CCID driver for PC/SC-Lite is used, which is the case for Linux and Mac OS X. Therefore, the SCardTransmit method shall be used instead on these systems (see PC/SC, using SCardTransmit paragraph below).

List the SpringCore PC/SC devices

SpringCoreTool.exe --pcsc --list

Note: all the tools, not only SpringCoreTool.exe*, do produce the same output when invoked with the* --list parameter.

The list of devices is constructed by looking for the SpringCard vendor name in the list of PC/SC readers returned by SCardListReaders. If your device is configured to expose a different vendor name, use --pcsc-all instead of --pcsc:

SpringCoreTool.exe --pcsc-all --list

For every (maybe) suitable reader found in SCardListReaders, the tool tries to open a direct connection with the reader to exchange a few SCardControl in order to make sure that the reader belongs to a SpringCore device.

If the tool fails to return any device, try the SCardTransmit method shall be used instead on these systems (see PC/SC, using SCardTransmit paragraph below).

You may also show a few technical data regarding the devices and their connection parameters using --list-details instead of --list.

Select one of the SpringCore PC/SC devices

If the --list command shows more than one device, use the --index=<INDEX> parameter to select the target device.

All the other parameters shall remain the same; for instance, to show the data of the second device (index 1), use:

SpringCoreTool.exe infos --pcsc --index=1

or, if the vendor name is not SpringCard:

SpringCoreTool.exe infos --pcsc-all --index=1

PC/SC, using SCardTransmit

This communication method works only if there is a smartcard in the reader and the tool is allowed to connect to the card (i.e. no other applicatin has already take an exclusive channel with the card).

List the SpringCore PC/SC devices

SpringCoreTool.exe --pcsc --transmit --list

Note: all the tools, not only SpringCoreTool.exe*, do produce the same output when invoked with the* --list parameter.

The list of devices is constructed by looking for the SpringCard vendor name in the list of PC/SC readers returned by SCardListReaders. If your device is configured to expose a different vendor name, use --pcsc-all instead of --pcsc:

SpringCoreTool.exe --pcsc-all --transmit --list

For every (maybe) suitable reader found in SCardListReaders, the tool tries to open a connection with the card inside the reader, to exchange a few “special” APDUs using SCardTransmit in order to make sure that the reader belongs to a SpringCore device.

If the tool fails to return any device, verify that you have inserted a smartcard in any contact or contactless slot of the device, and that no other application is currently connected to this smartcard.

You may also show a few technical data regarding the devices and their connection parameters using --list-details instead of --list.

Select one of the SpringCore PC/SC devices

If the --list command shows more than one device, use the --index=<INDEX> parameter to select the target device.

All the other parameters shall remain the same; for instance, to show the data of the second device (index 1), use:

SpringCoreTool.exe infos --pcsc --transmit --index=1

or, if the vendor name is not SpringCard:

SpringCoreTool.exe infos --pcsc-all --transmit --index=1

Network

Network, using UDP

Connect to a SpringCore device through UDP over the standard port

Once the IP address of the target SpringCore device is known, use the --network=udp://<IP ADDRESS> scheme to connect to the device.

Example:

SpringCoreTool.exe infos --network=udp://192.168.16.225

Connect to a SpringCore device through UDP over a specific port

If the devices uses a specific port for UDP communication, use the --network=udp://<IP ADDRESS>:<UDP PORT> scheme to connect to the device.

Example:

SpringCoreTool.exe infos --network=udp://192.168.16.225:3726

Advanced parameters

To be written

Network, using TCP

To be written

Going through the SpringCard Companion Service

The SpringCard Companion Service is an innovative gateway between the ‘technical’ world of SpringCard devices and high-end, cross-platform applications, including cloud-based solutions.

Please refer to SpringCard Companion online documentation for details.

When the Companion Service is running on a computer, it gets an exclusive access to all compliant SpringCore devices and exposes them through a set of REST and WebSocket APIs. The SpringCore Tools shall then go through the Companion Service to access the devices, instead of trying to connect them directly.

Detecting that SpringCard Companion Service is running

If one of the SpringCore Tools shows the following alert:

*****************************************************************************
* SpringCard Companion Service (or an other SpringCard Direct tool) is       *
* already running.                                                           *
*                                                                            *
* Please stop all instances of the Service before running this tool, and     *
* make sure that no other SpringCard Direct tool is running.                 *
******************************************************************************

this means either that another SpringCore Tool is already running in another terminal or (more likely) that the Companion Service is running in the background. In the later case, the tool also shows the service’s parameters:

Details:
        Process:   C:/springcard/companion-service/SpringCardCompanionSvc.exe
        Owner:     SPRINGCARD/johann.d
        REST API:  http://127.0.0.1:3998
        WebSocket: ws://127.0.0.1:3997

If the Companion Service is running, use the --companion parameter on the command line to instruct the SpringCore Tool to go through the service.

List the SpringCore devices through the Companion Service

SpringCoreTool.exe --companion --list

Note: all the tools, not only SpringCoreTool.exe*, do produce the same output when invoked with the* --list parameter.

You may also show a few technical data regarding the devices and their connection parameters using --list-details instead of --list.

Select one of the SpringCore devices through the Companion Service

If the --list command shows more than one device, use the --index=<INDEX> parameter to select the target device.

For instance, to show the data of the second device (index 1), use:

SpringCoreTool.exe infos --companion --index=1