Skip to main content
Kofax

Kofax SignDoc - SignPad Virtual Channel (VC)

20053

Summary

  • Date of Article: November 2017

Technical Insight: Kofax SignDoc - SignPad Virtual Channel (VC)

This Knowledge Base Article explains the Technology called Kofax SignDoc - SignPad Virtual Channel which can be used to leverage SignPads in a remote environment.

SignPad Virtual Channel supports Citrix / ICA  or Remote Desktop Protocol (RDP / Terminal Server) on Windows as well as Citrix / ICA on Linux.

For scenarios where Terminal Server on Linux is required please consider Kofax SignDoc - Virtual Serial SignPad (VSSP) since there is no official RDP Client on Linux which supports the Virtual Channel API.

Step 1: Installation/Preparation on Remote Client

Virtual Channel is a technology, which allows to have a dedicated path of communication between a remote client with a SignPad attached to it via USB, and a server connected via either Citrix or Terminal Server.
Please refer to the "Core - Virtual Channel" section in the Kofax SignDoc 2.0.1 Technical Specifications document  for a list of supported SignPads.
Under "Kofax Products" navigate to the product "Kofax SignDoc" -> "Documentation:" section -> Kofax SignDoc x.x.x Product Documentation (compressed) -> KofaxSignDocTechnicalSpecifications PDF document at bottom of article
At the date of this article the following SignPads are supported by Virtual Channel: WACOM STU-300, STU-430, STU- 500, STU-520, STU-530, STU-540 (not yet in Technical Specifications document)

As a prerequisite for Windows, Kofax SignDoc Device Support has to be installed on the client.
 

N.B.: In an environment where other Kofax E-Signature products (e.g. SignDoc Desktop) are installed already:
Please make sure to check the PATH environment variable before and after the installation and make sure, that all the paths relating to the SignDoc products are still present in the environment variable. In case that a path has been deleted, please re-set it.

Installing the Virtual Channel driver for ICA / Citrix on Windows (here: Windows 7 - x64)

  1. Find the ICA Client installation directory. It is either
    %USERPROFILE%\AppData\Local\Citrix\ICA Client
    or
    %ProgramFiles%\Citrix\ICA Client
    or
    %ProgramFiles(x86)%\Citrix\ICA Client
  2. Copy spvc32.dll from "c:\Program Files (x86)\SignDoc Device Support\Win32\" to the ICA Client installation directory
  3. Find the ICA Client registry key. It is either
    HKCU\Software\Citrix\ICA Client
    (if installed in %USERPROFILE%) or (if installed for all users)
    HKLM\Software\Citrix\ICA Client
    or
    HKLM\Software\Wow6432Node\Citrix\ICA Client
  4. In regedit, navigate to key Engine\Configuration\Advanced\Modules under the key determined in step (3).
    N.B.: If the ICA Client registry key can be found in multiple registry locations, please apply step (4) to the "HKLM\Software\Wow6432Node\Citrix\ICA Client" branch
  5. Create a new key "SPVC" and create a new string value named "DriverNameWin32" having value "spvc32.dll" under that key.
    Screen Shot 2018-09-21 at 10.47.58 AM.png
    Screen Shot 2018-09-21 at 10.48.25 AM.png
    (To disable HPC support, create a new string value named "HPC" having value "0" under that key. Do this only if the Virtual Channel does not work.)
  6. Set string value "VirtualDriverEx" under key "ICA 3.0" to "SPVC".
    If the string value is already non-empty, append a comma and "SPVC".
    Screen Shot 2018-09-21 at 10.50.44 AM.png
     

Installing the Virtual Channel driver for RDP on Windows (here: Windows 7 - x64)

  1. Copy spvc32.dll (for 32-bit systems) or spvc64.dll (for 64-bit systems) from "c:\Program Files (x86)\SignDoc Device Support\Win32" or "...\Win64" to a dedicated Virtual Channel directory, e.g. C:\VC.
  2. Add a subkey named SPVC to registry key HKCU\Software\Microsoft\Terminal Server Client\Default\AddIns
  3. Add a new string value named "Name" and having the pathname of the above DLL as value.
    For example:
    C:\VC\spvc64.dll

Installing the Virtual Channel driver for ICA / Citrix on Linux (here: Ubuntu 17.10 - x64)

Extract the Linux SPVC archive (here: spvc-3.1.41.0-linux-x86_64.tar.gz) into a temporary folder:tar -xvf spvc-3.1.41.0-linux-x86_64.tar.gz -C /tmp

  1. Copy spvc32.so (for the 32-bit ICA client) or spvc64.so (for the 64-bit ICA client) as well as the corresponding spvchelper file to /usr/lib and type:
    chmod 755 /usr/lib/spvchelper
  2. Find the ICA Client installation directory. It is either
    $HOME/ICA_Client/linuxx86
    or
    /opt/Citrix/ICAClient
  3. Edit the config/module.ini file in the ICA Client installation directory:
    • append ", SPVC" to the VirtualDriver line
    • In the "[ICA 3.0]" section (i.e., a comma and "SPVC")
    • Add this new section:
      [SPVC]
      DriverName=/usr/lib/spvc32.so
      (Use spvc64.so for the 64-bit ICA client.)
      To enable tracing via syslog, create a new line "TraceLevel=X" in the "[SPVC]" section, having a value between "1" and "5" for X.
      To use a file instead of syslog, add "TraceFile=P" where P is an strftime() template for the pathname of the file to be written to.
      Make sure that the user running the Citrix Receiver / Browser has sufficiant privileges to write to the log file.
      Example:
      TraceLevel=5
      TraceFile=/var/log/spvc-%Y-%m-%d.log
      Note: Old files won't be removed automatically.
      Screen Shot 2018-09-21 at 10.51.19 AM.png
      Example of Logging (/var/log/spvc-2017-11-06.log):

      2017-11-06T10:01:25.160947 opening channel SPRvc1
      2017-11-06T10:01:25.161219 writehook channel number=21, vdwh.pVdData=0x7f6d9bde2ae0, rc=0
      2017-11-06T10:01:25.161260 registered
      2017-11-06T10:01:25.533491 DriverPoll
      2017-11-06T10:01:26.203469 DriverSetInformation
      2017-11-06T10:01:26.205900 DriverInfo
      2017-11-06T10:01:26.205964 DriverInfo
  4. Run the installation script (from folder /tmp/spvc-3.1.41.0-linux-x86_64):
    ./install-spvc.sh install
    Screen Shot 2018-09-21 at 10.52.10 AM.png
    To uninstall the Virtual Channel driver, run
    ./install-spvc uninstall
    Screen Shot 2018-09-21 at 10.52.28 AM.png
    Finally, add those users who want to use the Virtual Channel driver to the signpad group

Step 2: Installation/Preparation on Citrix / Remote Desktop Server

As a prerequiste, Kofax SignDoc Device Support has to be installed on the server.

N.B.: In an environment where other Kofax E-Signature products (e.g. SignDoc Desktop) are installed already:
Please make sure to check the PATH environment variable before and after the installation and make sure, that all the paths relating to the SignDoc products are still present in the environment variable. In case that a path has been deleted, please re-set it.

There are no further settings necessary on the Server side for SignPad Virtual Channel to function properly.

If addtional configuration of the SignPad driver is required the Tablet.ini file needs to be used for this. SignDoc Device Support comes with a sample Tablet.ini file ("c:\Program Files (x86)\SignDoc Device Support\samples\Tablet.ini.sample") which should be copied to the folder that is included in the PATH environment variable (e.g. C:\Program Files (x86)\SignDoc Device Support\Win32 and others).
The Virtual Channel will be used if UsbPad of the Tablet.ini WSIGNPAD section is 0 or includes 16.
As the default value of UsbPad is 0, the Virtual Channel will automatically be used if there is no Tablet.ini file.

Additional information and parameters of the Tablet.ini file can be found in the SignWare documentation file "pg_PadInstallation.html"

Troubleshooting

For further investigation upon connectivity issues, please consult one of the means below ordered by protocol:

Tracing via DbgView for ICA / Citrix on Windows

To enable tracing, create a new string value named "TraceLevel" having a value between "1" and "5" under the key of Step (5) above at "Installing_the_Virtual_Channel_driver"
Use DbgView to view the output.

SPVC output of DbgView with SPVC "TraceLevel" set to value "5" in Windows Registry (after completing step (6) and a running Citrix Receiver):

Screen Shot 2018-09-21 at 10.53.22 AM.png
Tracing via DbgView for RDP on Windows

To enable tracing, create a new DWORD value named "TraceLevel"
having a Hex value between 1 and 5 under the key of Step (3) above (Installing the Virtual Channel driver for RDP on Windows (here: Windows 7 - x64).
Use DbgView to view the output.

SPVC output of DbgView with SPVC "TraceLevel" set to value "5" in Windows Registry (connect and disconnect via mstsc):

Screen Shot 2018-09-21 at 10.53.52 AM.png
Verification via Process Explorer on Windows

To verify whether the Virtual Channel DLL (spvc*.dll) is successfully loaded upon starting a Citrix session or connecting via Terminal Server the tool Process Explorer can be used.
After starting Process Explorer the search function (Ctrl + F) has to be used to verify whether the SPVC DLL file has been loaded successfully.
Please make sure to use the right bitness of Process Explorer according to the Citrix Receiver and mstsc version.

Successful search for SPVC DLL in Process Explorer while connecting via Citrix Receiver:

Screen Shot 2018-09-21 at 10.54.39 AM.png

Successful search for SPVC DLL in Process Explorer (2) while connecting via mstsc (1):

Screen Shot 2018-09-21 at 10.55.20 AM.png
Verification via SP_WspChk on Windows Client and Server side

To verify whether a connected SignPad can be found, this command can be used (on Client and Server side):
sp_wspchk -getuid2
The tool sp_wspchk.exe is part of the Kofax SignDoc Device Support setup.
A successful output looks similar to this:

Screen Shot 2018-09-21 at 10.55.42 AM.png
Verification via SignPadInit on Linux Client side

To verify whether a connected SignPad can be found, this command can be used: SignPadInit default
The tool SignPadInit is part of the Virtual Channel Linux package (here: spvc-3.1.41.0-linux-x86_64.tar.gz). A successful output looks similar to this:

Screen Shot 2018-09-21 at 10.56.14 AM.png

Applies to

Keywords: VC, Virtual Channel, Linux, Windows, Citrix, RDP