Skip to main content
Version: Developer

Smart Card Pass-through

Kasm Workspaces supports passing through smart card devices into both RDP-based Windows sessions and containerized workspace sessions. This feature enables users to use their physical smart cards within applications and systems, supporting various use cases such as PIN-based authentication, digital signing, and certificate-based operations.

For RDP-based Windows Sessions​

Configuration​

Group Settings​

Ensure the allow-kasm-smartcard-passthrough Group Setting is set to true prior to launching sessions that require smart card passthrough (both container-based and RDP-based workspaces).

Windows Target Environments​

  1. Prepare the environment by installing the manufacturer provided drivers, middleware, and certificates for the smart card readers and smart cards that will be used.

For Web Native Client​

To enable this feature on ChromeOS:

  1. Ensure the allow-kasm-smartcard-passthrough Group Setting is set to true

  2. Download and install the Kasm Native Smartcard Client as per the instructions in the Kasm Native Smartcard Client section below

  3. Install the Kasm Workspaces Smart Card Extension from the Chrome Web Store

  4. Launch a container-based Kasm session.

  5. Install the Kasm Workspaces Smart Card Extension from the Chrome Web Store.

  6. Ensure the allow_kasm_smart_card_passthrough Group Setting is set to true prior to launching the session.

    1. The smart card should now be automatically detected and made available to applications within the container.

Technical Details For Web Native Client​

This feature works by extending the guacamole protocol to enable smart card passthrough capabilities. The implementation leverages the Remote Desktop Protocol's smart card channel to securely transmit smart card operations between the client and the remote Windows system. While the implementation is PC/SC (Personal Computer/Smart Card) compliant, the available functions are limited to the functionality provided by the ChromeOS Smart Card Connector App. Any application attempting to use a PC/SC function unsupported on ChromeOS will receive an S_CARD_E_UNSUPPORTED error code as per PC/SC standard.

Due to the nature of smart card passthrough, cache related functionality (which is normally part of the Windows platform) had to be emulated. For security reasons, the corresponding PC/SC functions (SCardReadCache and SCardWriteCache) are implemented in the Chrome extension rather than on the server side. This approach ensures that sensitive cached smart card data remains local to the user's browser.

Technical Details For RDP Local Client​

This feature is implemented via the RDP client's implementation of the feature and may have limitations based on that specific implementation.

Troubleshooting​

For Web Native Client​

If you encounter issues with smart card passthrough:

  1. Ensure your smart card reader is properly connected
  2. Ensure the allow_kasm_smart_card_passthrough group setting is enabled
  3. Ensure the Google Smart Card Connector App Chrome extension is enabled
  4. Ensure the DriveLock Smart Card Middleware (CSSI) Chrome extension is enabled
  5. Ensure the Kasm Workspaces Smart Card Extension Chrome extension is enabled
  6. Ensure that any drivers, middleware, or certificates that are required by the smartcard and smartcard reader manufacturers are installed on the system.
  7. If the smart card appears to be in an unresponsive state, try removing and reinserting the card

If you're still experiencing issues, these additional troubleshooting tools are available:

Client-side Troubleshooting:

  1. Check chrome://extensions and inspect the Kasm Workspaces Smart Card Extension service worker for detailed logs about client-side smart card operations.
  2. Check the Native Client detailed logs:

Log file path: %APPDATA%\Kasm\Smart Card Bridge\logs\kasm_scard_bridge.log
Alternative log file path: C:\temp\kasm-logs\kasm_scard_bridge.log

Note

The alternative log file path is used when the Native Client is unable to write to the normal log path. This is usually due to the Native Client not having write permissions to the desired folder.

Note

A new log file is generated each time the Native Client is launched, or when the active log file reaches a size of 10 MB. The system maintains a maximum of four log files. Once this limit is reached, the Native Client will overwrite the oldest log file with a new one, ensuring that only the four most recent log files are retained.

Server-side Troubleshooting:

  1. Check the kasm_guac container logs for smartcard related messages
  2. Look for a Registering smartcard container log message to confirm smartcard support was enabled for the session

Diagnostic Tools:

  1. Open Command Prompt or PowerShell in the Windows session
  2. Run certutil -scinfo to get detailed information about connected smart card readers and cards. This tool can help identify if Windows properly recognizes the smart card hardware.

For certificate-enabled smartcards:

  1. Verify the certificate has been recognized:
    • Press Win + R, type certmgr.msc, and press Enter.
    • In the left pane, expand Personal → Certificates.
    • Look for a certificate issued by your smartcard's Certificate Authority.
  2. In case of a missing client certificate, verify the presence of necessary configuration entries in the Windows registry at HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Calais\SmartCards for your smartcard. Missing entries can prevent proper smartcard certificate propagation, affecting smartcard functionality.

For RDP Local Client​

  1. Ensure your smart card reader is properly connected
  2. Ensure the allow_kasm_smart_card_passthrough group setting is enabled
  3. Ensure that any drivers, middleware, or certificates that are required by the smartcard and smartcard reader manufacturers are installed on the system.
  4. If the smart card appears to be in an unresponsive state, try removing and reinserting the card

If you're still experiencing issues:

Check the documentation and troubleshooting guides for the RDP client.

Diagnostic Tools:

  1. Open Command Prompt or PowerShell in the Windows session
  2. Run certutil -scinfo to get detailed information about connected smart card readers and cards. This tool can help identify if Windows properly recognizes the smart card hardware.

For Container-based Workspaces​

Container-based workspaces support smart card passthrough by creating a virtual smartcard reader within the container that forwards commands to the physical smartcard connected to the user's device via the Kasm Smartcard Chrome extension. The implementation maintains full container isolation as it requires no privileged container access or external host mounts.

Note

For performance reasons, while disconnecting the reader or card will have immediate effect within the container, an inserted card might be detected with a slight delay (no longer than 2-3 seconds).

Configuration​

To enable this feature:

  1. Ensure the allow_kasm_smart_card_passthrough Group Setting is set to true prior to launching the session.

  2. Install the required components for your operating system:

  1. Download and install the Kasm Native Smartcard Client as per the instructions in the Kasm Native Smartcard Client section below
  2. Install the Kasm Workspaces Smart Card Extension from the Chrome Web Store

  1. Launch a container-based Kasm session.

  2. Once enabled, the live smartcard passthrough status will be visible under "Control Panel > Smartcard Passthrough".

  3. The smart card should now be automatically detected and made available to applications within the container.

Kasm Native Smartcard Client​

The Kasm Native Smartcard Client is a native host application that enables smartcard functionality for container-based workspaces by bridging communication between the browser extension and local smartcard readers on Windows and macOS systems.

Installation​

Windows:

  • Download and run the .msi installer package
  • The installer automatically places the application in C:\Program Files\Kasm\Smart Card Bridge\ and registers it with Chrome for native messaging

macOS:

  • Download and run the .pkg installer package
  • The installer places the application in /Library/Application Support/Kasm/Smart Card Bridge/ and configures native messaging in /Library/Google/Chrome/NativeMessagingHosts/

Verification​

To verify the native client is working properly:

  1. Open chrome://extensions/ in your browser
  2. Find the Kasm Workspaces Smart Card Extension
  3. Click background page under the extension
  4. Look for the following messages in the console: 
    Initializing smartcard native client...
    Smartcard native client initialized

Technical Implementation​

Container-based smart card passthrough uses a multi-component architecture that maintains container security through virtual device emulation:

  • PC/SC Daemon (pcscd) runs within the container to provide standard PC/SC services
  • VPCD (Virtual PC/SC Device) creates a virtual smartcard reader named "Kasm Remote Smartcard" that appears as a standard PC/SC reader to applications within the container
  • Kasm Smartcard Bridge (kasm_smartcard_bridge) acts as a VPCD server, translating between the VPCD protocol and KasmVNC's relay protocol
  • Kasm Web App coordinates communication between browser and container
  • Kasm Chrome Extension communicates with either the native client (Windows/macOS) or directly with ChromeOS exposed APIs
  • Kasm Native Smartcard Client interfaces with the physical smartcard reader on Windows and macOS

This architecture allows applications to use standard PC/SC APIs seamlessly without requiring privileged container access or host system mounts.

The communication flow is: Container Applications → PC/SC Daemon → VPCD ("Kasm Remote Smartcard") → Smartcard Bridge → KasmVNC Relay → Web App → Chrome Extension → Native Client/ChromeOS APIs → Physical Reader

Troubleshooting For Container-based Workspaces​

If you encounter issues with smart card passthrough in containers:

  1. Ensure your smart card reader is properly connected
  2. Ensure the allow_kasm_smart_card_passthrough group setting is enabled
  3. Ensure the Kasm Native Smartcard Client is installed and running
  4. Ensure the Kasm Workspaces Smart Card Extension Chrome extension is enabled
  5. Check the smartcard status under "Control Panel > Smartcard Passthrough" to verify the status of each component (extension/reader/card)
  6. Verify that the container has smartcard support enabled (KASM_SVC_SMARTCARD=1)
  7. If the smart card appears to be in an unresponsive state, try removing and reinserting the card

Client-side Troubleshooting:

  1. Check the smartcard status under "Control Panel > Smartcard Passthrough" to verify the status of each component (extension/reader/card)
  2. Check chrome://extensions and inspect the Kasm Workspaces Smart Card Extension service worker for detailed logs about client-side smart card operations
  3. Verify the native client is running in the system process list

Container-side Troubleshooting:

  1. Check the container logs for smartcard related errors (pcscd/bridge)
  2. Check if the PC/SC daemon is running: docker exec CONTAINER_ID ps aux | grep pcscd
  3. Check if the smartcard bridge is running: docker exec CONTAINER_ID ps aux | grep kasm_smartcard_bridge
  4. Test PC/SC connectivity within the container: docker exec CONTAINER_ID opensc-tool -l -a

Diagnostic Tools:

  1. Within the container, run docker exec CONTAINER_ID opensc-tool --list-readers to see available readers
  2. Run docker exec CONTAINER_ID opensc-tool --atr to verify the card is detected
  3. Run docker exec CONTAINER_ID opensc-tool --serial to verify the card data transmission works
  4. Use docker exec CONTAINER_ID pkcs15-tool --list-certificate to list certificates on the card