You've already forked vsmartcard
mirror of
https://github.com/librekeys/vsmartcard.git
synced 2026-04-14 08:46:17 -07:00
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>USB CCID Emulator — vsmartcard 2021-04-28 documentation</title>
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="../_static/bootstrap-sphinx.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="../_static/graphviz.css" />
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script src="../_static/jquery.js"></script>
<script src="../_static/underscore.js"></script>
<script src="../_static/doctools.js"></script>
<script src="../_static/js/jquery-1.11.0.min.js"></script>
<script src="../_static/js/jquery-fix.js"></script>
<script src="../_static/bootstrap-3.3.7/js/bootstrap.min.js"></script>
<script src="../_static/bootstrap-sphinx.js"></script>
<link rel="shortcut icon" href="../_static/chip.ico"/>
<link rel="search" title="Search" href="../search.html" />
<link rel="next" title="Creating a Virtual Smart Card" href="../virtualsmartcard/api.html" />
<link rel="prev" title="PC/SC Relay" href="../pcsc-relay/README.html" />
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
</head><body>
<a href="https://github.com/frankmorgner/vsmartcard"
class="visible-desktop hidden-xs"><img
id="gh-banner"
style="position: absolute; top: 50px; right: 0; border: 0;"
src="https://s3.amazonaws.com/github/ribbons/forkme_right_white_ffffff.png"
alt="Fork me on GitHub"></a>
<script>
// Adjust banner height.
$(function () {
var navHeight = $(".navbar .container").css("height");
$("#gh-banner").css("top", navHeight);
});
</script>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="../index.html">
vsmartcard</a>
<span class="navbar-text navbar-version pull-left"><b></b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="dropdown globaltoc-container">
<a role="button"
id="dLabelGlobalToc"
data-toggle="dropdown"
data-target="#"
href="../index.html">Site <b class="caret"></b></a>
<ul class="dropdown-menu globaltoc"
role="menu"
aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../virtualsmartcard/README.html">Virtual Smart Card</a></li>
<li class="toctree-l1"><a class="reference internal" href="../remote-reader/README.html">Remote Smart Card Reader</a></li>
<li class="toctree-l1"><a class="reference internal" href="../ACardEmulator/README.html">Android Smart Card Emulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="../TCardEmulator/README.html">Tizen Smart Card Emulator</a></li>
<li class="toctree-l1"><a class="reference internal" href="../pcsc-relay/README.html">PC/SC Relay</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">USB CCID Emulator</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../virtualsmartcard/api.html">Creating a Virtual Smart Card</a></li>
</ul>
</ul>
</li>
<li class="dropdown">
<a role="button"
id="dLabelLocalToc"
data-toggle="dropdown"
data-target="#"
href="#">Page <b class="caret"></b></a>
<ul class="dropdown-menu localtoc"
role="menu"
aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">USB CCID Emulator</a><ul>
<li><a class="reference internal" href="#download">Download</a></li>
<li><a class="reference internal" href="#installation">Installation</a><ul>
<li><a class="reference internal" href="#installation-on-linux-unix-and-similar">Installation on Linux, Unix and similar</a></li>
<li><a class="reference internal" href="#hints-on-gadgetfs">Hints on GadgetFS</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usage">Usage</a></li>
<li><a class="reference internal" href="#question">Question</a></li>
<li><a class="reference internal" href="#notes-and-references">Notes and References</a></li>
</ul>
</li>
</ul>
</ul>
</li>
<li>
<a href="../pcsc-relay/README.html" title="Previous Chapter: PC/SC Relay"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« PC/SC Relay</span>
</a>
</li>
<li>
<a href="../virtualsmartcard/api.html" title="Next Chapter: Creating a Virtual Smart Card"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Creating a Vi... »</span>
</a>
</li>
<li class="hidden-sm"></li>
</ul>
<form class="navbar-form navbar-right" action="../search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
</div>
<div class="container">
<div class="row">
<div class="col-md-12 content">
<div class="section" id="usb-ccid-emulator">
<span id="ccid-emulator"></span><h1>USB CCID Emulator<a class="headerlink" href="#usb-ccid-emulator" title="Permalink to this headline">¶</a></h1>
<div class="sidebar">
<p class="sidebar-title">Emulate a USB CCID compliant smart card reader</p>
<dl class="field-list simple">
<dt class="field-odd">License</dt>
<dd class="field-odd"><p>GPL version 3</p>
</dd>
<dt class="field-even">Tested Platforms</dt>
<dd class="field-even"><p>Linux (Debian, Ubuntu, OpenMoko)</p>
</dd>
</dl>
</div>
<p>The USB CCID Emulator forwards a locally present PC/SC smart card reader as a
standard USB CCID reader. USB CCID Emulator can be used as trusted intermediary
enabling secure PIN entry and PIN modification. In combination with <a class="reference external" href="https://github.com/frankmorgner/OpenSC">OpenSC</a> <a class="footnote-reference brackets" href="#id7" id="id8">2</a>
also <abbr title="Password Authenticated Connection Establishment">PACE</abbr> can be performed by the emulator.</p>
<div class="figure" id="id1" style="text-align: center">
<p><img src="../_images/tikz-1281452b980f69540bc7520179e10f3ccc59fe36.svg" alt="Figure made with TikZ" /></p>
<p class="caption"><span class="caption-text">Portable smart card reader with trusted user interface</span></p>
</div><p>If the machine running <strong class="command">ccid-emulator</strong> is in USB device mode, a local
reader is forwareded via USB to another machine. If in USB host mode, the USB
CCID reader will locally be present.</p>
<p>Applications on Windows and Unix-like systems can access the USB CCID Emulator
through PC/SC as if it was a real smart card reader. No installation of a smart
card driver is required since USB CCID drivers are usually shipped with the
modern OS.</p>
<p>Here is a subset of USB CCID commands supported by the USB CCID Emulator with
their PC/SC counterpart:</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 36%" />
<col style="width: 64%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>USB CCID</p></th>
<th class="head"><p>PC/SC</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">PC_to_RDR_XfrBlock</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">SCardTransmit</span></code></p></td>
</tr>
<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">PC_to_RDR_Secure</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FEATURE_VERIFY_PIN_DIRECT</span></code>, <code class="docutils literal notranslate"><span class="pre">FEATURE_MODIFY_PIN_DIRECT</span></code></p></td>
</tr>
<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">PC_to_RDR_Secure</span></code> (proprietary)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">FEATURE_EXECUTE_PACE</span></code></p></td>
</tr>
</tbody>
</table>
<p>PIN verification/modification and <abbr title="Password Authenticated Connection Establishment">PACE</abbr> can also be started by the application
transmitting (SCardTransmit) specially crafted APDUs. Only the alternative
initialization of <abbr title="Password Authenticated Connection Establishment">PACE</abbr> using SCardControl requires patching the driver
(available for libccid, see <code class="file docutils literal notranslate"><span class="pre">patches</span></code>). The pseudo APDUs with no need for
patches are defined as follows (see <a class="reference external" href="https://www.bsi.bund.de/DE/Publikationen/TechnischeRichtlinien/tr03119/index_htm.html">BSI TR-03119 1.3</a> <a class="footnote-reference brackets" href="#id16" id="id17">6</a> p. 33-34):</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 18%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 7%" />
<col style="width: 22%" />
<col style="width: 24%" />
<col style="width: 8%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head" rowspan="2"></th>
<th class="head" colspan="5"><p>Command APDU</p></th>
<th class="head" colspan="2"><p>Response APDU</p></th>
</tr>
<tr class="row-even"><th class="head"><p>CLA</p></th>
<th class="head"><p>INS</p></th>
<th class="head"><p>P1</p></th>
<th class="head"><p>P2</p></th>
<th class="head"><p>Command Data</p></th>
<th class="head"><p>Response Data</p></th>
<th class="head"><p>SW1/SW2</p></th>
</tr>
</thead>
<tbody>
<tr class="row-odd"><td><p>GetReaderPACECapabilities</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0xFF</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x9A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x04</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x01</span></code></p></td>
<td><p>(No Data)</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">PACECapabilities</span></code></p></td>
<td rowspan="4"><p><code class="docutils literal notranslate"><span class="pre">0x9000</span></code>
or other
in case of
an error</p></td>
</tr>
<tr class="row-even"><td><p>EstablishPACEChannel</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0xFF</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x9A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x04</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x02</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EstablishPACEChannelInput</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">EstablishPACEChannelOutput</span></code></p></td>
</tr>
<tr class="row-odd"><td><p>DestroyPACEChannel</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0xFF</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x9A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x04</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x03</span></code></p></td>
<td><p>(No Data)</p></td>
<td><p>(No Data)</p></td>
</tr>
<tr class="row-even"><td><p>Verify/Modify PIN</p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0xFF</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x9A</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x04</span></code></p></td>
<td><p><code class="docutils literal notranslate"><span class="pre">0x10</span></code></p></td>
<td><p>Coding as <code class="docutils literal notranslate"><span class="pre">PC_to_RDR_Secure</span></code></p></td>
<td><p>Coding as <code class="docutils literal notranslate"><span class="pre">RDR_to_PC_DataBlock</span></code></p></td>
</tr>
</tbody>
</table>
<p>The USB CCID Emulator is implemented using <a class="reference external" href="http://www.linux-usb.org/gadget/">GadgetFS</a> <a class="footnote-reference brackets" href="#id4" id="id5">1</a>. Some fragments of the source
code are based on the GadgetFS example and on the source code of the OpenSC
tools.</p>
<div class="figure" id="id2" style="text-align: center">
<p><img src="../_images/tikz-5b402031da401947efbeae7481d47bd35196791d.svg" alt="Figure made with TikZ" /></p>
<p class="caption"><span class="caption-text">Software stack of the USB CCID Emulator running on the OpenMoko Neo FreeRunner</span></p>
</div><p>Running the USB CCID Emulator has the following dependencies:</p>
<ul class="simple">
<li><p>Linux Kernel with <a class="reference external" href="http://www.linux-usb.org/gadget/">GadgetFS</a> <a class="footnote-reference brackets" href="#id4" id="id6">1</a></p></li>
<li><p><a class="reference external" href="https://github.com/frankmorgner/OpenSC">OpenSC</a> <a class="footnote-reference brackets" href="#id7" id="id9">2</a></p></li>
</ul>
<p>Whereas using the USB CCID Emulator on the host system as smart card reader only
needs a usable PC/SC middleware with USB CCID driver. This is the case for most
modern Windows and Unix-like systems by default.</p>
<div class="figure" id="id3" style="text-align: center">
<p><img src="../_images/tikz-6e71605956d62bb837a2533794c8c50348b2f87c.svg" alt="Figure made with TikZ" /></p>
<p class="caption"><span class="caption-text">Implementation of a mobile smart card reader for the German ID card</span></p>
</div><div class="section" id="download">
<h2>Download<a class="headerlink" href="#download" title="Permalink to this headline">¶</a></h2>
<p>You can find the latest release of USB CCID Emulator on <a class="reference external" href="https://github.com/frankmorgner/vsmartcard/releases">Github</a>. Older releases are
still available on <a class="reference external" href="http://sourceforge.net/projects/vsmartcard/files">Sourceforge</a>.</p>
<p>Alternatively, you can clone our git repository:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git clone https://github.com/frankmorgner/vsmartcard.git
</pre></div>
</div>
</div>
<div class="section" id="installation">
<h2>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h2>
<div class="section" id="installation-on-linux-unix-and-similar">
<h3>Installation on Linux, Unix and similar<a class="headerlink" href="#installation-on-linux-unix-and-similar" title="Permalink to this headline">¶</a></h3>
<p>The USB CCID Emulator uses the GNU Build System to compile and install. If you are
unfamiliar with it, please have a look at <code class="file docutils literal notranslate"><span class="pre">INSTALL</span></code>. If you can not find
it, you are probably working bleeding edge in the repository. To generate the
missing standard auxiliary files you need to additionally install <cite>libtool</cite> and
<cite>pkg-config</cite> and run the following command in <code class="file docutils literal notranslate"><span class="pre">ccid-emulator</span></code>:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>autoreconf --verbose --install
</pre></div>
</div>
<p>To configure (<strong class="command">configure --help</strong> lists possible options), build and
install the USB CCID Emulator now do the following:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>./configure
make
make install
</pre></div>
</div>
<p>The USB CCID Emulator depends on <strong class="program">libopensc</strong>, which is automatically
built from a snapshot of the OpenSC source code and then statically linked.</p>
</div>
<div class="section" id="hints-on-gadgetfs">
<h3>Hints on GadgetFS<a class="headerlink" href="#hints-on-gadgetfs" title="Permalink to this headline">¶</a></h3>
<p>To create a USB Gadget in both USB host and USB client mode, you need to load
the kernel module <strong class="program">gadgetfs</strong>. Here is how to get a running version of
GadgetFS on a Debian system (see also <a class="reference external" href="http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module">OpenMoko Wiki</a> <a class="footnote-reference brackets" href="#id14" id="id15">5</a>):</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>sudo apt-get install linux-source linux-headers-<span class="sb">`</span>uname -r<span class="sb">`</span>
sudo tar xjf /usr/src/linux-source-*.tar.bz2
<span class="nb">cd</span> linux-source-*/drivers/usb/gadget
<span class="c1"># build dummy_hcd and gadgetfs</span>
<span class="nb">echo</span> <span class="s2">"KDIR := /lib/modules/`uname -r`/build"</span> >> Makefile
<span class="nb">echo</span> <span class="s2">"PWD := `pwd`"</span> >> Makefile
<span class="nb">echo</span> <span class="s2">"obj-m := dummy_hcd.o gadgetfs.o"</span> >> Makefile
<span class="nb">echo</span> <span class="s2">"default: "</span> >> Makefile
<span class="nb">echo</span> -e <span class="s2">"\t\$(MAKE) -C \$(KDIR) SUBDIRS=\$(PWD) modules"</span> >> Makefile
make
<span class="c1"># load GadgetFS with its dependencies</span>
sudo modprobe udc-core
sudo insmod ./dummy_hcd.ko
sudo insmod ./gadgetfs.ko <span class="nv">default_uid</span><span class="o">=</span><span class="sb">`</span>id -u<span class="sb">`</span>
<span class="c1"># mount GadgetFS</span>
sudo mkdir /dev/gadget
sudo mount -t gadgetfs gadgetfs /dev/gadget
</pre></div>
</div>
<p>On OpenMoko it is likely that you need to <a class="reference external" href="http://docs.openmoko.org/trac/ticket/2206">patch your kernel</a>. If you also want to switch
multiple times between <strong class="program">gadgetfs</strong> and <strong class="program">g_ether</strong>, <a class="reference external" href="http://docs.openmoko.org/trac/ticket/2240)">another
patch is needed</a>.</p>
<p>If you are using a more recent version of <strong class="program">dummy_hcd</strong> and get an error
loading the module, you maybe want to check out <a class="reference external" href="http://comments.gmane.org/gmane.linux.usb.general/47440">this patch</a>.</p>
</div>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>The USB CCID Emulator has various command line options to customize the appearance
on the USB host. In order to run the USB CCID Emulator GadgetFS must be loaded
and mounted. The USB CCID Emulator is compatible with the unix driver <a class="reference external" href="https://ccid.apdu.fr/">libccid</a> <a class="footnote-reference brackets" href="#id10" id="id11">3</a>
and the <a class="reference external" href="http://msdn.microsoft.com/en-us/windows/hardware/gg487509">Windows USB CCID driver</a> <a class="footnote-reference brackets" href="#id12" id="id13">4</a>. PIN commands are supported if implemented
by the driver.</p>
<div class="versionadded">
<p><span class="versionmodified added">New in version 0.7: </span>USB CCID Emulator now supports the boxing commands defined in <a class="reference external" href="https://www.bsi.bund.de/DE/Publikationen/TechnischeRichtlinien/tr03119/index_htm.html">BSI TR-03119
1.3</a> <a class="footnote-reference brackets" href="#id16" id="id18">6</a>.</p>
</div>
<div class="highlight-text notranslate"><div class="highlight"><pre><span></span>Usage: ccid-emulator [OPTION]...
Emulate a USB CCID compliant smart card reader
-h, --help Print help and exit
-V, --version Print version and exit
-i, --info Print available readers and drivers. (default=off)
-r, --reader=INT Number of the PC/SC reader to use (-1 for
autodetect) (default=`-1')
--gadgetfs=FILENAME Directory where GadgetFS is mounted
(default=`/dev/gadget')
-v, --verbose Use (several times) to be more verbose
Changing the appearance on the Universal Serial Bus:
-p, --product=INT USB product ID (default=`0x3010')
-e, --vendor=INT USB vendor ID (default=`0x0D46')
--serial=STRING USB serial number (default=`random')
--interface=STRING USB serial number (default=`notification status')
--interrupt Add interrupt pipe for CCID (default=off)
Report bugs to https://github.com/frankmorgner/vsmartcard/issues
Written by Frank Morgner <frankmorgner@gmail.com>
</pre></div>
</div>
</div>
<div class="section" id="question">
<h2>Question<a class="headerlink" href="#question" title="Permalink to this headline">¶</a></h2>
<p>Do you have questions, suggestions or contributions? Feedback of any kind is
more than welcome! Please use our <a class="reference external" href="https://github.com/frankmorgner/vsmartcard/issues">project trackers</a>.</p>
</div>
<div class="section" id="notes-and-references">
<h2>Notes and References<a class="headerlink" href="#notes-and-references" title="Permalink to this headline">¶</a></h2>
<dl class="footnote brackets">
<dt class="label" id="id4"><span class="brackets">1</span><span class="fn-backref">(<a href="#id5">1</a>,<a href="#id6">2</a>)</span></dt>
<dd><p><a class="reference external" href="http://www.linux-usb.org/gadget/">http://www.linux-usb.org/gadget/</a></p>
</dd>
<dt class="label" id="id7"><span class="brackets">2</span><span class="fn-backref">(<a href="#id8">1</a>,<a href="#id9">2</a>)</span></dt>
<dd><p><a class="reference external" href="https://github.com/frankmorgner/OpenSC">https://github.com/frankmorgner/OpenSC</a></p>
</dd>
<dt class="label" id="id10"><span class="brackets"><a class="fn-backref" href="#id11">3</a></span></dt>
<dd><p><a class="reference external" href="https://ccid.apdu.fr/">https://ccid.apdu.fr/</a></p>
</dd>
<dt class="label" id="id12"><span class="brackets"><a class="fn-backref" href="#id13">4</a></span></dt>
<dd><p><a class="reference external" href="http://msdn.microsoft.com/en-us/windows/hardware/gg487509">http://msdn.microsoft.com/en-us/windows/hardware/gg487509</a></p>
</dd>
<dt class="label" id="id14"><span class="brackets"><a class="fn-backref" href="#id15">5</a></span></dt>
<dd><p><a class="reference external" href="http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module">http://wiki.openmoko.org/wiki/Building_Gadget_USB_Module</a></p>
</dd>
<dt class="label" id="id16"><span class="brackets">6</span><span class="fn-backref">(<a href="#id17">1</a>,<a href="#id18">2</a>)</span></dt>
<dd><p><a class="reference external" href="https://www.bsi.bund.de/DE/Publikationen/TechnischeRichtlinien/tr03119/index_htm.html">https://www.bsi.bund.de/DE/Publikationen/TechnischeRichtlinien/tr03119/index_htm.html</a></p>
</dd>
</dl>
</div>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
© Copyright 2009-2021 by Dominik Oepen and Frank Morgner.<br/>
</p>
</div>
</footer>
</body>
</html>