Windows – Install and Set Up the PCSC Driver (optional)

This section describes how to install, configure, and manage the Oracle Java Card PCSC driver to enable communication with the Oracle Java Card Development Kit Simulator on Windows.

The package includes several files, each with a specific role in the driver setup.

Package Contents and File Descriptions

File Purpose
jcdkPCSC.cat (Catalog File) Provides digital signatures that verify the authenticity and integrity of the driver package. Ensures security and compliance during installation.
jcdkPCSC.sys (System File) The core device driver that enables communication between Windows and the Oracle Java Card Development Kit Simulator.
jcdkPCSCBus.inf (Information File) Contains installation instructions and configuration details for the PCSC bus driver. Used by Windows to properly recognize and install the driver.
jcdkPCSCReader.inf (Information File) Contains installation instructions for the simulated smart card reader device.
jcdkPCSCCtrl.exe (Driver Controller Application) A command-line tool to install, uninstall, and configure the PCSC driver, replacing and extending Windows Device Manager actions for this device.

Driver Controller Application Commands

Command Description
install Installs the PCSC driver (adds a Bus device to Windows, visible as “Oracle Java Card PCSC Bus” under System devices in Device Manager).
uninstall Uninstalls the PCSC driver and removes all simulated card readers.
add <identifier> Adds a simulated smart card reader for the Oracle Java Card Development Kit Simulator.

Note: <identifier> must be a numeric value (e.g. `0`). Only one reader can be added in the current version. The reader will appear in Windows Device Manager as Oracle Java Card PCSC Reader under Smart Card Readers.

remove <identifier> Removes the simulated reader specified by <identifier>.

Install PCSC Driver

Pre-requisites

  • Windows 10/11 (x64) and administrator privileges.
  • Uninstall any previous version of the driver (see Uninstall section).

Note:

Administrator privileges are required to install system drivers. All commands must be run from an elevated Command Prompt.
  1. Open a Command Prompt as Administrator.

    Navigate to the drivers/PCSC folder where the Oracle Java Card Development Kit Simulator package was installed. 

    cd drivers\PCSC
  2. Install the PCSC driver.

    Use the Driver Controller application to install the core PCSC driver. This registers a new PCSC Bus device, visible as Oracle Java Card PCSC Bus in the System devices category in Windows Device Manager. 

    jcdkPCSCCtrl.exe install
    New bus installed
  3. Add a simulated smart card reader.
    Add a simulated card reader for the Oracle Java Card Development Kit Simulator.

    Note:

    <identifier> must be a numeric value (e.g. `0`). Only one reader can be added in the current version. 
    jcdkPCSCCtrl.exe add 0 
    Reader added

    The reader will appear in Device Manager as Oracle Java Card PCSC Reader under Smart Card Readers.

Configure PCSC Driver for Remote or Custom Connections (optional)

By default, the driver connects to the Simulator running locally on localhost:9025. For more details how to start the Simulator, see Java Card Development Kit Simulator Command Line.

To connect to a Simulator on a different network address or port, update the default PCSC Driver configuration as follows:

  1. Open Windows Registry Editor.
  2. Choose the reader used to communicate with the Simulator. The reader instance is created under this path:
    Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\jcdkPCSCBus\jcdkPCSCReader
  3. Open the dynamically created reader instance and select the Device Parameters container:
    Computer\HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Enum\jcdkPCSCBus\jcdkPCSCReader\...\Device Parameters
  4. Edit the default values under Device Parameters:
    SimuIP REG_SZ 127.0.0.1 
SimuPort REG_DWORD 0x00002341 (9025)
  5. Restart the reader device: In Device Manager, select the Oracle Java Card PCSC Reader, choose Disable, then Enable the device.

Uninstall PCSC Driver

Note:

Administrator privileges are required to install system drivers. Run all commands from an elevated Command Prompt in the PCSC Driver folder of your JCDK bundle.
There are multiple ways to uninstall the driver:
  • Using the Driver Controller Application (jcdkPCSCCtrl.exe) – preferred solution
  • Using Windows Device Manager Control Panel

If you plan to install a newer version of the driver, we recommend performing the cleanup operations described at the end of this section.

Uninstall using the Oracle Driver Controller Application (Preferred)

  1. Open a Command Prompt as Administrator and navigate to the driver directory.

    Navigate to the drivers/PCSC folder where the Oracle Java Card Development Kit Simulator package was installed. 

    cd drivers\PCSC
  2. Remove the simulated reader.

    Use the Driver Controller application to remove the installed reader. The <identifier> must match the reader you previously added with the add <identifier> command. 

    jcdkPCSCCtrl.exe remove 0
    Reader removed
  3. Uninstall the PCSC driver.

    Use the Driver Controller application to uninstall the core PCSC driver. 

    jcdkPCSCCtrl.exe uninstall
    All buses uninstalled

Uninstall using Windows Device Manager

Choose one of the following methods:
  • Option 1 (Step-by-step removal):
    1. In Device Manager, find and right-click Oracle Java Card PCSC Reader under Smart Card Readers, then select Uninstall device.
    2. Next, find and right-click Oracle Java Card PCSC Bus under System devices, and select Uninstall device.
  • Option 2 (Remove parent device):
    1. In Device Manager, find and right-click Oracle Java Card PCSC Bus under System devices, then select Uninstall device.

      This will also automatically uninstall the associated PCSC Reader(s).

Cleanup using Windows PnPUtil Application

When you uninstall a device, Windows may only remove the device instance, not the driver files from the Driver Store. If the device is re-added, Windows can silently reinstall the same driver. To fully remove a problematic or outdated driver and prevent automatic reinstallation, execute the following steps in a PowerShell console opened as Administrator:

  1. Remove SmartCardReader drivers.
    pnputil /enum-drivers /class SmartCardReader
    Review the output for a section similar to: 
    
Published Name:    oemXXX.inf 
Original Name:     jcdkpcscreader.inf 
Provider Name:     Oracle 
Class Name:        SmartCardReader 
Class GUID:        {50dd5230-ba8a-11d1-bf5d-0000f805f530} 
Driver Version:    ... 
Signer Name:       Microsoft Windows Hardware Compatibility Publisher
    Then run: 
    pnputil /delete-driver oemXXX.inf /uninstall
  2. Remove System Bus drivers.
    pnputil /enum-drivers /class System | Select-String "Oracle" -Context 3,7
    Review the output for:
    
Published Name    oemXXX.inf 
Original Name:    jcdkpcscbus.inf 
Provider Name:    Oracle Corporation 
Class Name:       System 
Class GUID:       {4d36e97d-e325-11ce-bfc1-08002be10318} 
Driver Version:   ... 
Signer Name:      Microsoft Windows Hardware Compatibility Publisher
    Then run:
    pnputil /delete-driver oemXXX.inf /uninstall

Known Limitations and Issues

  • Single Reader Limitation

    Only one smart card reader can be added in the current version.

  • Simulated Reader State Not Updated When Simulator Stops

    Problem:

    When the Simulator is stopped, the PC/SC stack fails to update the simulated reader state to SCARD_ABSENT. As a result, applications relying on card removal detection may not respond as expected.

    Impact:

    • For applications using winscard.h:
      • SCardStatus(} may still report SCARD_PRESENT even though the Simulator is no longer running.
    • SCardGetStatusChange() can remain blocked despite the Simulator having been stopped.
    • SCardConnect() may continue to succeed for a short period after the Simulator is stopped, due to delayed state updates. After this brief window, subsequent connect attempts will fail as expected.
    • For applications using javax.smartcardio:
      • CardTerminal.waitForCardAbsent() may remain blocked despite the Simulator having been stopped.

    Workaround:

    To force a reader state refresh after stopping the Simulator, attempt to connect and then disconnect from the reader.

    This operation will trigger detection that the Simulator is no longer running, updating the state:
    • Using winscard.h: Call SCardConnect() followed by SCardDisconnect().
    • Using javax.smartcardio : Use CardTerminal.connect(*) to attempt a connection, then Card.disconnect()

    This will update the PC/SC stack and should unblock any logic waiting for a card absent state (SCARD_ABSENT).

    Recommendation:

    Where possible, implement timeouts or cancellation in your application logic to avoid indefinite blocking in case the Simulator has stopped unexpectedly.

Troubleshooting

  • Issue: Error 0x00000514 when running the Driver Controller Application (jcdkPCSCCtrl.exe)
    • Details:
      Error 0x00000514 
Not all privileges or groups referenced are assigned to the caller.
    • Solution:
      • This issue occurs when attempting to execute the Driver Controller Application without administrator privileges.
      • Open the Command Prompt as Administrator.
      • Re-run your command, for example: 
        jcdkPCSCCtrl.exe install
  • Issue: Error 0x000005AA when re-installing a Smart Card Reader.
    • Details:
      Last error: 000005AA 
Error adding reader: Insufficient system resources exist to complete the requested service
    • Solution:

      Uninstall the PCSC driver and re-install it as described above.