Virtual Smart Card¶

Installation on Linux, Unix and similar¶

The Virtual Smart Card uses the GNU Build System to compile and install. If you are unfamiliar with it, please have a look at INSTALL. If you can not find it, you are probably working bleeding edge in the repository. Run the following command in virtualsmartcard to get the missing standard auxiliary files:

autoreconf --verbose --install

To configure (configure --help lists possible options), build and install the Virtual Smart Card now do the following:

./configure --sysconfdir=/etc
make
make install

Building and installing vpcd on Mac OS X¶

Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows using the standard routine for installation on Unix.

Mac OS X 10.10 (and later) ships with a proprietary implementation of the PC/SC layer instead of with PCSC-Lite. As far as we know, this means that smart card readers must be USB devices instead of directly allowing a more generic type of reader. To make vpcd work we simply configure it to pretend being a USB smart card reader with an Ìnfo.plist:

./configure --prefix=/ --enable-infoplist
make
make install

Building and installing vpcd on Windows¶

For the Windows integration we extended Fabio Ottavi’s UMDF Driver for a Virtual Smart Card Reader [14] with a vpcd interface. To build vpcd for Windows we use Windows Driver Kit 8.1 and Visual Studio 2013 [15]. If you choose to download the Windows binaries [18], you may directly jump to step 3.

1. In Visual Studio select File ‣ Open ‣ Convert Sources/Dirs... and choose the vpcd’s sources either in the WinXP [1] or Win7 folder.

   When successfully imported, ensure with the configuration manager, that both of the created projects are built for the same platform (x64 or Win32).

2. If you can successfully Build the solution, you can find the install package in BixVReader-package. It contains BixVReader.inf and the required libraries, especially BixVReader.dll and WudfUpdate_01009.dll [2].

3. Copy win32\BixVReader\BixVReader.ini into the %SystemRoot% directory.

4. In a console with administrator rights go to BixVReader-package and install the driver:

   "C:\Program Files\Windows Kits\8.1\Tools\x86\devcon.exe" install BixVReader.inf root\BixVirtualReader
   

   You can adjust the path to devcon.exe with your version of the WDK and your target architecture (e.g., use ...\x64\devcon.exe for a 64 bit driver). You can also download DevCon’s source code [16] and compile it yourself.

   For Win7 and older, code signing is optional and will yield a warning during installation when missing. Simply click continue to install the driver anyway.

   To activate the WDK test signing, use VS build-in Driver Signing settings. Right click BixVReader-package Properties ‣ Driver Signing ‣ Sign Mode ‣ Test Sign. Import the WDKTestCert certificate BixVReader-package.cer into your windows keystore (e.g. on local computer) and then install the driver. See Microsoft’s Kernel-Mode Code Signing Walkthrough [17] for details.

For debugging vpcd and building the driver with an older version of Visual Studio or WDK please see Fabio Ottavi’s UMDF Driver for a Virtual Smart Card Reader [14] for details. All of Fabio’s card connectors (pipe reader/TCP/IP reader) are still active by default.

Configuring vpcd on Unix¶

The configuration file of vpcd is usually placed into /etc/reader.conf.d/. For older versions of PCSC-Lite you need to run update-reader.conf to update pcscd‘s main configuration file. The PC/SC daemon should read it and load the vpcd on startup. In debug mode pcscd -f -d should say something like “Attempting startup of Virtual PCD” when loading vpcd.

By default, vpcd opens a socket for vpicc and waits for incoming connections. The port to open should be specified in CHANNELID and DEVICENAME:

FRIENDLYNAME "Virtual PCD"
DEVICENAME   /dev/null:0x8C7B
LIBPATH      /usr/lib/pcsc/drivers/serial/libifdvpcd.so
CHANNELID    0x8C7B

If the first part of the DEVICENAME is different from /dev/null, vpcd will use this string as a hostname for connecting to a waiting vpicc. vpicc needs to be started with --reversed in this case.

Configuring vpcd on Mac OS X¶

Mac OS X 10.9 and earlier is using PCSC-Lite as smart card service which allows using the standard routine for configuration on Unix.

On Mac OS X 10.10 you should have configured the generation of Info.plist at compile time. Now do the following for registering vpcd as USB device:

1. Choose an USB device (e.g. mass storage, phone, mouse, ...), which will be used to start vpcd. Plug it into the computer.

2. Run the following command to get the device’s product and vendor ID:

   system_profiler SPUSBDataType
   

3. Change /usr/libexec/SmartCardServices/drivers/ifd-vpcd.bundle/Info.plist to match your product and vendor ID:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>CFBundleDevelopmentRegion</key>
	<string>English</string>
	<key>CFBundleExecutable</key>
	<string>libifdvpcd.dylib</string>
	<key>CFBundleInfoDictionaryVersion</key>
	<string>6.0</string>
	<key>CFBundleName</key>
	<string>ifd-vpcd</string>
	<key>CFBundlePackageType</key>
	<string>BNDL</string>
	<key>CFBundleSignature</key>
	<string>????</string>
	<key>CFBundleVersion</key>
	<string>0.8</string>

	<key>ifdManufacturerString</key>
	<string>Virtual Smart Card Architecture</string>
	<key>ifdProductString</key>
	<string>Virtual PCD</string>

	<key>ifdCapabilities</key>
	<string>0x00000000</string>
	<key>ifdProtocolSupport</key>
	<string>0x00000001</string>
	<key>ifdVersionNumber</key>
	<string>0x00000001</string>

	<key>ifdVendorID</key>
	<array>
		<string>0x18d1</string>
	</array>

	<key>ifdProductID</key>
	<array>
		<string>0x4ee1</string>
	</array>

	<key>ifdFriendlyName</key>
	<array>
		<string>/dev/null:0x8C7B</string>
	</array>

	<key>Copyright</key>
	<string>This driver is protected by terms of the GNU General Public License version 3, or (at your option) any later version.</string>
</dict>
</plist>

Note that ifdFriendlyName can be used in the same way as DEVICENAME described above.

4. Restart the PC/SC service:

   sudo killall -SIGKILL -m .*com.apple.ifdreader
   

Now, every time you plug in your USB device vpcd will be started. It will be stopped when you unplug the device.

Configuring vpcd on Windows¶

The configuration file BixVReader.ini of vpcd is usually placed into C:\Windows (SystemRoot). The user mode device driver framework (WUDFHost.exe) should read it automatically and load the vpcd on startup. The Windows Device Manager mmc devmgmt.msc should list the Bix Virtual Smart Card Reader.

vpcd opens a socket for vpicc and waits for incoming connections. The port to open should be specified in TCP_PORT:

[Driver]
NumReaders=3

[Reader0]
RPC_TYPE=0
VENDOR_NAME=Fabio Ottavi
VENDOR_IFD_TYPE=Pipe Reader
DECIVE_UNIT=0

[Reader1]
RPC_TYPE=1
VENDOR_NAME=Fabio Ottavi
VENDOR_IFD_TYPE=TCP/IP Reader
DECIVE_UNIT=1

[Reader2]
RPC_TYPE=2
VENDOR_NAME=Virtual Smart Card Architecture
VENDOR_IFD_TYPE=Virtual PCD
TCP_PORT=35963
DECIVE_UNIT=2

Currently it is not possible to configure the Windows driver to connect to an vpicc running with --reversed.

Running vpicc¶

The compiled Windows binaries [18] of vpicc include OpenPACE. The other dependencies listed above need to be installed seperately. You can start the vpicc via python.exe vicc.py. On all other systems an executable script vicc is installed using the autotools.

The vpicc option --help gives an overview about the command line switches:

usage: vicc [-h] [-t {iso7816,cryptoflex,ePass,nPA,relay,handler_test}] [-v]
            [-f FILE] [-H HOSTNAME] [-P PORT] [-R] [--version]
            [--reader READER] [--ef-cardaccess EF_CARDACCESS]
            [--ef-cardsecurity EF_CARDSECURITY] [--cvca CVCA]
            [--disable-ta-checks] [--ca-key CA_KEY] [-d DATASETFILE]
            [--esign-cert ESIGN_CERT] [--esign-ca-cert ESIGN_CA_CERT]

Virtual Smart Card 0.8: Smart card emulator written in Python. The emulator
connects to the virtual smart card reader reader (vpcd). Smart card
applications can access the Virtual Smart Card through the vpcd via PC/SC.

optional arguments:
  -h, --help            show this help message and exit
  -t {iso7816,cryptoflex,ePass,nPA,relay,handler_test}, --type {iso7816,cryptoflex,ePass,nPA,relay,handler_test}
                        type of smart card to emulate (default: iso7816)
  -v, --verbose         Use (several times) to be more verbose
  -f FILE, --file FILE  load a saved smart card image
  -H HOSTNAME, --hostname HOSTNAME
                        specifiy vpcd's host name if vicc shall connect to it.
                        (default: localhost)
  -P PORT, --port PORT  port of connection establishment (default: 35963)
  -R, --reversed        use reversed connection mode. vicc will wait for an
                        incoming connection from vpcd. (default: False)
  --version             show program's version number and exit

Relaying a local smart card (`--type=relay`):
  --reader READER       number of the reader containing the card to be relayed
                        (default: 0)

Emulation of German identity card (`--type=nPA`):
  --ef-cardaccess EF_CARDACCESS
                        the card's EF.CardAccess (default: use file from first
                        generation nPA)
  --ef-cardsecurity EF_CARDSECURITY
                        the card's EF.CardSecurity (default: use file from
                        first generation nPA)
  --cvca CVCA           trust anchor for verifying certificates in TA
                        (default: use libeac's trusted certificates)
  --disable-ta-checks   disable checking the validity period of CV certifcates
                        (default: False)
  --ca-key CA_KEY       the chip's private key for CA (default: randomly
                        generated, invalidates signature of EF.CardSecurity)
  -d DATASETFILE, --datasetfile DATASETFILE
                        Load the smartcard's data groups (DGs) from the
                        specified dataset file. For DGs not in dataset file
                        default values are used. The data groups in the data
                        set file must have the following syntax:
                        ---------------------------------------------------
                        Datagroupname=Datagroupvalue
                        ---------------------------------------------------
                        For Example: GivenNames=GERTRUD. The following Dataset
                        Elements may be used in the dataset file:
                        DocumentType, IssuingState, DateOfExpiry, GivenNames,
                        FamilyNames, ReligiousArtisticName, AcademicTitle,
                        DateOfBirth, PlaceOfBirth, Nationality, Sex,
                        BirthName, Country, City, ZIP, Street, CommunityID,
                        ResidencePermit1, ResidencePermit2, dg12, dg14, dg15,
                        dg16, dg21.
  --esign-cert ESIGN_CERT
                        the card holder's certificate for QES
  --esign-ca-cert ESIGN_CA_CERT
                        the CA's certificate for QES

Report bugs to https://github.com/frankmorgner/vsmartcard/issues

When vpcd and vpicc are connected you should be able to access the card through the PC/SC API. You can use the opensc-explorer or pcsc_scan for testing. In Virtual Smart Card’s root directory we also provide scripts for testing with npa-tool [19] and PCSC-Lite’s smart card reader driver tester.