VivoKey/vsmartcard
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

added documentation about TCardEmulator

Browse Source 
rebuilt docs with 'pdf2svg' for tizk images
This commit is contained in:
Frank Morgner
2017-01-16 01:29:58 +01:00
parent 7c1f8f2a7e
commit 7e70c87dde
96 changed files with 42654 additions and 13024 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/virtualsmartcard/api.html
View File

@@ -5,7 +5,7 @@
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>Creating a Virtual Smart Card &mdash; vsmartcard 2017-01-08 documentation</title>
<title>Creating a Virtual Smart Card &mdash; vsmartcard 2017-01-16 documentation</title>
<link rel="stylesheet" href="../_static/basic.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
@@ -15,7 +15,7 @@
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
VERSION: '2017-01-08',
VERSION: '2017-01-16',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
@@ -29,7 +29,7 @@
<script type="text/javascript" src="../_static/bootstrap-3.3.4/js/bootstrap.min.js"></script>
<script type="text/javascript" src="../_static/bootstrap-sphinx.js"></script>
<link rel="shortcut icon" href="../_static/chip.ico"/>
<link rel="top" title="vsmartcard 2017-01-08 documentation" href="../index.html" />
<link rel="top" title="vsmartcard 2017-01-16 documentation" href="../index.html" />
<link rel="next" title="virtualsmartcard Package" href="api/virtualsmartcard.html" />
<link rel="prev" title="USB CCID Emulator" href="../ccid/README.html" />
<meta charset='utf-8'>
@@ -38,7 +38,7 @@
<meta name="apple-mobile-web-app-capable" content="yes">
</head>
<body role="document">
<body>
<a href="https://github.com/frankmorgner/vsmartcard"
class="visible-desktop hidden-xs"><img
@@ -85,6 +85,7 @@
<li class="toctree-l1"><a class="reference internal" href="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"><a class="reference internal" href="../ccid/README.html">USB CCID Emulator</a></li>
</ul>
@@ -157,8 +158,8 @@
<div class="section" id="creating-a-virtual-smart-card">
<span id="virtualsmartcard-api"></span><h1>Creating a Virtual Smart Card<a class="headerlink" href="#creating-a-virtual-smart-card" title="Permalink to this headline"></a></h1>
<p><abbr title="virtual smart card reader">vpcd</abbr> communicates over a socked with <abbr title="virtual smart card">vpicc</abbr> usually on port <code class="docutils literal"><span class="pre">0x8C7B</span></code>
(configurably via <code class="file docutils literal"><span class="pre">/etc/reader.conf.d/vpcd</span></code>). So you can connect
<p><abbr title="virtual smart card reader">vpcd</abbr> communicates over a socked with <abbr title="virtual smart card">vpicc</abbr> usually on port <tt class="docutils literal"><span class="pre">0x8C7B</span></tt>
(configurably via <tt class="file docutils literal"><span class="pre">/etc/reader.conf.d/vpcd</span></tt>). So you can connect
virtually any program to the virtual smart card reader, as long as you respect
the following protocol:</p>
<table border="1" class="docutils" id="vpcd-commands">
@@ -179,29 +180,29 @@ the following protocol:</p>
</tr>
</thead>
<tbody valign="top">
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></code></td>
<td><code class="docutils literal"><span class="pre">0x00</span></code> (Power Off)</td>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></tt></td>
<td><tt class="docutils literal"><span class="pre">0x00</span></tt> (Power Off)</td>
<td>&nbsp;</td>
<td>(No Response)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></code></td>
<td><code class="docutils literal"><span class="pre">0x01</span></code> (Power On)</td>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></tt></td>
<td><tt class="docutils literal"><span class="pre">0x01</span></tt> (Power On)</td>
<td>&nbsp;</td>
<td>(No Response)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></code></td>
<td><code class="docutils literal"><span class="pre">0x02</span></code> (Reset)</td>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></tt></td>
<td><tt class="docutils literal"><span class="pre">0x02</span></tt> (Reset)</td>
<td>&nbsp;</td>
<td>(No Response)</td>
</tr>
<tr class="row-even"><td><code class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></code></td>
<td><code class="docutils literal"><span class="pre">0x04</span></code> (Get ATR)</td>
<td><code class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></code></td>
<tr class="row-even"><td><tt class="docutils literal"><span class="pre">0x00</span> <span class="pre">0x01</span></tt></td>
<td><tt class="docutils literal"><span class="pre">0x04</span></tt> (Get ATR)</td>
<td><tt class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></tt></td>
<td>(ATR)</td>
</tr>
<tr class="row-odd"><td><code class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></code></td>
<tr class="row-odd"><td><tt class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></tt></td>
<td>(APDU)</td>
<td><code class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></code></td>
<td><tt class="docutils literal"><span class="pre">0xXX</span> <span class="pre">0xXX</span></tt></td>
<td>(R-APDU)</td>
</tr>
</tbody>
@@ -255,14 +256,14 @@ ISO 7816. But as for most complex software you need to know where you need to
hook into. Here we only want to give an overview to the design, the complete
details can be found in section <a class="reference internal" href="#documentation-to-virtual-smart-card">Documentation to Virtual Smart Card</a>.</p>
<p>Back to the cryptoflex example.
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><code class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></code></a> provides the connection
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><tt class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></tt></a> provides the connection
to the virtual smart card reader. It fetches an <abbr title="Application Protocol Data Unit">APDU</abbr> and other requests from
the <abbr title="virtual smart card reader">vpcd</abbr>. In <a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><code class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></code></a> an <abbr title="Application Protocol Data Unit">APDU</abbr>
the <abbr title="virtual smart card reader">vpcd</abbr>. In <a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><tt class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></tt></a> an <abbr title="Application Protocol Data Unit">APDU</abbr>
is only a buffer that is forwarded to the smart card OS. First we modify
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><code class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></code></a> to recognize a new type
<code class="docutils literal"><span class="pre">&quot;cryptoflex&quot;</span></code> and to load
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexOS" title="virtualsmartcard.cards.cryptoflex.CryptoflexOS"><code class="xref py py-class docutils literal"><span class="pre">CryptoflexOS</span></code></a>. The
<a class="reference internal" href="api/virtualsmartcard.CardGenerator.html#module-virtualsmartcard.CardGenerator" title="virtualsmartcard.CardGenerator"><code class="xref py py-class docutils literal"><span class="pre">CardGenerator</span></code></a> is used to create a file system and a
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><tt class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></tt></a> to recognize a new type
<tt class="docutils literal"><span class="pre">&quot;cryptoflex&quot;</span></tt> and to load
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexOS" title="virtualsmartcard.cards.cryptoflex.CryptoflexOS"><tt class="xref py py-class docutils literal"><span class="pre">CryptoflexOS</span></tt></a>. The
<a class="reference internal" href="api/virtualsmartcard.CardGenerator.html#module-virtualsmartcard.CardGenerator" title="virtualsmartcard.CardGenerator"><tt class="xref py py-class docutils literal"><span class="pre">CardGenerator</span></tt></a> is used to create a file system and a
<abbr title="Secure Access Module">SAM</abbr> specific to the cryptoflex (we come back to this later).</p>
<div class="highlight-python"><div class="highlight"><pre> <span class="k">def</span> <span class="nf">__init__</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">datasetfile</span><span class="p">,</span> <span class="n">card_type</span><span class="p">,</span> <span class="n">host</span><span class="p">,</span> <span class="n">port</span><span class="p">,</span>
<span class="n">readernum</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">ef_cardsecurity</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span> <span class="n">ef_cardaccess</span><span class="o">=</span><span class="bp">None</span><span class="p">,</span>
@@ -359,7 +360,7 @@ is only a buffer that is forwarded to the smart card OS. First we modify
<p>Responses from our cryptoflex card look the same as for the 7816 card. But when
a command was successfull (or not) there is a little difference in what is
returned. So we need to edit
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexOS.formatResult" title="virtualsmartcard.cards.cryptoflex.CryptoflexOS.formatResult"><code class="xref py py-class docutils literal"><span class="pre">formatResult</span></code></a>, which is
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexOS.formatResult" title="virtualsmartcard.cards.cryptoflex.CryptoflexOS.formatResult"><tt class="xref py py-class docutils literal"><span class="pre">formatResult</span></tt></a>, which is
called to encode the <abbr title="status bytes SW 1 and SW 2">SWs</abbr> and the resulting data.</p>
<div class="highlight-python"><div class="highlight"><pre> <span class="k">def</span> <span class="nf">formatResult</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">ins</span><span class="p">,</span> <span class="n">le</span><span class="p">,</span> <span class="n">data</span><span class="p">,</span> <span class="n">sw</span><span class="p">):</span>
<span class="k">if</span> <span class="n">le</span> <span class="o">==</span> <span class="mi">0</span> <span class="ow">and</span> <span class="nb">len</span><span class="p">(</span><span class="n">data</span><span class="p">):</span>
@@ -383,15 +384,15 @@ called to encode the <abbr title="status bytes SW 1 and SW 2">SWs</abbr> and the
</pre></div>
</div>
<p>Note that this also requires some insight knowledge about how
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.Iso7816OS" title="virtualsmartcard.VirtualSmartcard.Iso7816OS"><code class="xref py py-class docutils literal"><span class="pre">Iso7816OS</span></code></a> works.</p>
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.Iso7816OS" title="virtualsmartcard.VirtualSmartcard.Iso7816OS"><tt class="xref py py-class docutils literal"><span class="pre">Iso7816OS</span></tt></a> works.</p>
<p>The previously created <abbr title="Secure Access Module">SAM</abbr> handles keys, encryption, secure messaging and so
on (we will not go into more details here). The file system creates, selects
and reads contents of files or directories. File handling for our cryptoflex
card is similar to ISO 7816, but the meaning of P1, P2 and the <abbr title="Application Protocol Data Unit">APDU</abbr> data is
completely different when creating a file on the smart card. So we derive
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexMF" title="virtualsmartcard.cards.cryptoflex.CryptoflexMF"><code class="xref py py-class docutils literal"><span class="pre">CryptoflexMF</span></code></a> from
<a class="reference internal" href="api/virtualsmartcard.SmartcardFilesystem.html#virtualsmartcard.SmartcardFilesystem.MF" title="virtualsmartcard.SmartcardFilesystem.MF"><code class="xref py py-class docutils literal"><span class="pre">MF</span></code></a> and modify
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexMF.create" title="virtualsmartcard.cards.cryptoflex.CryptoflexMF.create"><code class="xref py py-class docutils literal"><span class="pre">create</span></code></a> to our needs.</p>
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexMF" title="virtualsmartcard.cards.cryptoflex.CryptoflexMF"><tt class="xref py py-class docutils literal"><span class="pre">CryptoflexMF</span></tt></a> from
<a class="reference internal" href="api/virtualsmartcard.SmartcardFilesystem.html#virtualsmartcard.SmartcardFilesystem.MF" title="virtualsmartcard.SmartcardFilesystem.MF"><tt class="xref py py-class docutils literal"><span class="pre">MF</span></tt></a> and modify
<a class="reference internal" href="api/virtualsmartcard.cards.cryptoflex.html#virtualsmartcard.cards.cryptoflex.CryptoflexMF.create" title="virtualsmartcard.cards.cryptoflex.CryptoflexMF.create"><tt class="xref py py-class docutils literal"><span class="pre">create</span></tt></a> to our needs.</p>
<div class="highlight-python"><div class="highlight"><pre> <span class="k">def</span> <span class="nf">create</span><span class="p">(</span><span class="n">p1</span><span class="p">,</span> <span class="n">p2</span><span class="p">,</span> <span class="n">data</span><span class="p">):</span>
<span class="k">if</span> <span class="n">data</span><span class="p">[</span><span class="mi">0</span><span class="p">:</span><span class="mi">2</span><span class="p">]</span> <span class="o">!=</span> <span class="s">&quot;</span><span class="se">\xff\xff</span><span class="s">&quot;</span><span class="p">:</span>
@@ -445,11 +446,11 @@ your modifications...</p>
magic that is done while parsing a buffer (an <abbr title="Application Protocol Data Unit">APDU</abbr>). As example we will
connect to an other smart card using PC/SC and forward it to <abbr title="virtual smart card reader">vpcd</abbr>.</p>
<p>As before with the cryptoflex card, we let
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><code class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></code></a> recognize the new type
<code class="docutils literal"><span class="pre">&quot;relay&quot;</span></code>. <a class="reference internal" href="api/virtualsmartcard.cards.Relay.html#virtualsmartcard.cards.Relay.RelayOS" title="virtualsmartcard.cards.Relay.RelayOS"><code class="xref py py-class docutils literal"><span class="pre">RelayOS</span></code></a> overwrites all
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.VirtualICC" title="virtualsmartcard.VirtualSmartcard.VirtualICC"><tt class="xref py py-class docutils literal"><span class="pre">VirtualICC</span></tt></a> recognize the new type
<tt class="docutils literal"><span class="pre">&quot;relay&quot;</span></tt>. <a class="reference internal" href="api/virtualsmartcard.cards.Relay.html#virtualsmartcard.cards.Relay.RelayOS" title="virtualsmartcard.cards.Relay.RelayOS"><tt class="xref py py-class docutils literal"><span class="pre">RelayOS</span></tt></a> overwrites all
main functions from the template
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.SmartcardOS" title="virtualsmartcard.VirtualSmartcard.SmartcardOS"><code class="xref py py-class docutils literal"><span class="pre">SmartcardOS</span></code></a>. Its functions correspond
to the <a class="reference internal" href="#vpcd-commands"><span>commands sent by vpcd</span></a>. If you know how to use
<a class="reference internal" href="api/virtualsmartcard.VirtualSmartcard.html#virtualsmartcard.VirtualSmartcard.SmartcardOS" title="virtualsmartcard.VirtualSmartcard.SmartcardOS"><tt class="xref py py-class docutils literal"><span class="pre">SmartcardOS</span></tt></a>. Its functions correspond
to the <a class="reference internal" href="#vpcd-commands"><em>commands sent by vpcd</em></a>. If you know how to use
<a class="reference external" href="http://pyscard.sourceforge.net/">pyscard</a> then the rest is pretty straight
forward, but see yourself...</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">RelayOS</span><span class="p">(</span><span class="n">SmartcardOS</span><span class="p">):</span>