Files
vsmartcard/docs/virtualsmartcard/api/virtualsmartcard.cards.ePass.html
2023-09-27 03:03:35 +02:00

826 lines
40 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>ePass Module &#8212; vsmartcard 2023-09-27 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>
<link rel="shortcut icon" href="../../_static/chip.ico"/>
<link rel="search" title="Search" href="../../search.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">
<script type="text/javascript" src="../../_static/js/jquery-1.11.0.min.js "></script>
<script type="text/javascript" src="../../_static/js/jquery-fix.js "></script>
<script type="text/javascript" src="../../_static/bootstrap-3.3.7/js/bootstrap.min.js "></script>
<script type="text/javascript" src="../../_static/bootstrap-sphinx.js "></script>
</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>
<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>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../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="#">ePass Module</a></li>
</ul>
</ul>
</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="body col-md-12 content" role="main">
<div class="section" id="epass-module">
<h1>ePass Module<a class="headerlink" href="#epass-module" title="Permalink to this headline"></a></h1>
<div class="graphviz"><img src="../../_images/inheritance-4597a997c71c5ba82a2efa2f624f6bda3bcd578a.png" alt="Inheritance diagram of virtualsmartcard.cards.ePass" usemap="#inheritancef880455e0d" class="inheritance graphviz" /></div>
<map id="inheritancef880455e0d" name="inheritancef880455e0d">
<area shape="rect" id="node1" href="virtualsmartcard.SEutils.html#virtualsmartcard.SEutils.Security_Environment" target="_top" title="virtualsmartcard.SEutils.Security_Environment" alt="" coords="5,55,331,80"/>
<area shape="rect" id="node4" href="#virtualsmartcard.cards.ePass.ePass_SE" target="_top" title="This class implements the Security Environment of the ICAO Passports. It" alt="" coords="391,55,665,80"/>
<area shape="rect" id="node2" href="virtualsmartcard.SmartcardSAM.html#virtualsmartcard.SmartcardSAM.SAM" target="_top" title="This class is used to store the data needed by the SAM." alt="" coords="35,5,301,31"/>
<area shape="rect" id="node3" href="#virtualsmartcard.cards.ePass.PassportSAM" target="_top" title="SAM for ICAO ePassport. Implements Basic access control and key derivation" alt="" coords="379,5,677,31"/>
</map><span class="target" id="module-virtualsmartcard.cards.ePass"></span><dl class="py class">
<dt id="virtualsmartcard.cards.ePass.PassportSAM">
<em class="property"><span class="pre">class</span> </em><code class="sig-prename descclassname"><span class="pre">virtualsmartcard.cards.ePass.</span></code><code class="sig-name descname"><span class="pre">PassportSAM</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mf</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="virtualsmartcard.SmartcardSAM.html#virtualsmartcard.SmartcardSAM.SAM" title="virtualsmartcard.SmartcardSAM.SAM"><code class="xref py py-class docutils literal notranslate"><span class="pre">virtualsmartcard.SmartcardSAM.SAM</span></code></a></p>
<p>SAM for ICAO ePassport. Implements Basic access control and key derivation
for Secure Messaging.</p>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.FSdecrypt">
<code class="sig-name descname"><span class="pre">FSdecrypt</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.FSdecrypt" title="Permalink to this definition"></a></dt>
<dd><p>Decrypt the given data, using the parameters stored in the SAM.
Right now we do not encrypt the data. In memory encryption might or
might not be added in a future version.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.FSencrypt">
<code class="sig-name descname"><span class="pre">FSencrypt</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.FSencrypt" title="Permalink to this definition"></a></dt>
<dd><p>Encrypt the given data, using the parameters stored in the SAM.
Right now we do not encrypt the data. In memory encryption might or
might not be added in a future version.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.__computeKeys">
<code class="sig-name descname"><span class="pre">__computeKeys</span></code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.__computeKeys" title="Permalink to this definition"></a></dt>
<dd><p>Computes the keys depending on the machine readable
zone of the passport according to TR-PKI mrtds ICC read-only
access v1.1 annex E.1.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM._get_referenced_key">
<code class="sig-name descname"><span class="pre">_get_referenced_key</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM._get_referenced_key" title="Permalink to this definition"></a></dt>
<dd><p>This method returns the key specified by the p2 parameter. The key may
be stored on the cards filesystem.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>p1</strong> Specifies the algorithm to use.</p></li>
<li><p><strong>p2</strong> <p>Specifies a reference to the key to be used for encryption.</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 3%" />
<col style="width: 73%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>b8</p></th>
<th class="head"><p>b7</p></th>
<th class="head"><p>b6</p></th>
<th class="head"><p>b5</p></th>
<th class="head"><p>b4</p></th>
<th class="head"><p>b3</p></th>
<th class="head"><p>b2</p></th>
<th class="head"><p>b1</p></th>
<th class="head"><p>Meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>No information is given</p></td>
</tr>
<tr class="row-odd"><td><p>0</p></td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><p>Global reference data(e.g. MF specific key)</p></td>
</tr>
<tr class="row-even"><td><p>1</p></td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><p>Specific reference data(e.g. DF specific
key)</p></td>
</tr>
<tr class="row-odd"><td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><ul>
<li></li>
</ul>
</td>
<td><p>x</p></td>
<td><p>x</p></td>
<td><p>x</p></td>
<td><p>x</p></td>
<td><p>x</p></td>
<td><p>Number of the secret</p></td>
</tr>
</tbody>
</table>
<p>Any other value RFU</p>
</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.change_reference_data">
<code class="sig-name descname"><span class="pre">change_reference_data</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.change_reference_data" title="Permalink to this definition"></a></dt>
<dd><p>Change the specified referenced data (e.g. CHV) of the card</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.derive_key">
<em class="property"><span class="pre">static</span> </em><code class="sig-name descname"><span class="pre">derive_key</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">seed</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">c</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.derive_key" title="Permalink to this definition"></a></dt>
<dd><p>Derive a key according to TR-PKI mrtds ICC read-only access v1.1
annex E.1.
c is either 1 for encryption or 2 for MAC computation.
Returns: Ka + Kb
Note: Does not adjust parity. Nobody uses that anyway …</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.erase_SE">
<code class="sig-name descname"><span class="pre">erase_SE</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">SEID</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.erase_SE" title="Permalink to this definition"></a></dt>
<dd><p>Erases a Security Environment stored under SEID from the SAM</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.external_authenticate">
<code class="sig-name descname"><span class="pre">external_authenticate</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">resp_data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.external_authenticate" title="Permalink to this definition"></a></dt>
<dd><p>Performs the basic access control protocol as defined in
the ICAO MRTD standard</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.generate_public_key_pair">
<code class="sig-name descname"><span class="pre">generate_public_key_pair</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.generate_public_key_pair" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.get_card_number">
<code class="sig-name descname"><span class="pre">get_card_number</span></code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.get_card_number" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.get_challenge">
<code class="sig-name descname"><span class="pre">get_challenge</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.get_challenge" title="Permalink to this definition"></a></dt>
<dd><p>Generate a random number of maximum 8 Byte and return it.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.internal_authenticate">
<code class="sig-name descname"><span class="pre">internal_authenticate</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.internal_authenticate" title="Permalink to this definition"></a></dt>
<dd><p>Authenticate card to terminal. Encrypt the challenge of the terminal
to prove key posession</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.manage_security_environment">
<code class="sig-name descname"><span class="pre">manage_security_environment</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.manage_security_environment" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.mutual_authenticate">
<code class="sig-name descname"><span class="pre">mutual_authenticate</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">mutual_challenge</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.mutual_authenticate" title="Permalink to this definition"></a></dt>
<dd><p>Takes an encrypted challenge in the form
Terminal Challenge | Card Challenge | Card number
and checks it for validity. If the challenge is successful
the card encrypts Card Challenge | Terminal challenge and
returns this value</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.parse_SM_CAPDU">
<code class="sig-name descname"><span class="pre">parse_SM_CAPDU</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">CAPDU</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">header_authentication</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.parse_SM_CAPDU" title="Permalink to this definition"></a></dt>
<dd><p>Parse a command APDU protected by Secure Messaging and return the
unprotected command APDU</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.perform_security_operation">
<code class="sig-name descname"><span class="pre">perform_security_operation</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.perform_security_operation" title="Permalink to this definition"></a></dt>
<dd></dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.protect_result">
<code class="sig-name descname"><span class="pre">protect_result</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">unprotected_result</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.protect_result" title="Permalink to this definition"></a></dt>
<dd><p>Protect a plain response APDU by Secure Messaging</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.restore_SE">
<code class="sig-name descname"><span class="pre">restore_SE</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">SEID</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.restore_SE" title="Permalink to this definition"></a></dt>
<dd><p>Restores a Security Environment from the SAM and replaces the current
SE with it.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.set_MF">
<code class="sig-name descname"><span class="pre">set_MF</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">mf</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.set_MF" title="Permalink to this definition"></a></dt>
<dd><p>Setter function for the internal reference to the Filesystem. The SAM
needs a reference to the filesystem in order to store/retrieve keys.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.set_asym_algorithm">
<code class="sig-name descname"><span class="pre">set_asym_algorithm</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">cipher</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">keytype</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.set_asym_algorithm" title="Permalink to this definition"></a></dt>
<dd><dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>cipher</strong> Public/private key object from used for encryption</p></li>
<li><p><strong>keytype</strong> Type of the public key (e.g. RSA, DSA)</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.store_SE">
<code class="sig-name descname"><span class="pre">store_SE</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">SEID</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.store_SE" title="Permalink to this definition"></a></dt>
<dd><p>Stores the current Security environment in the secure access module.
The SEID is used as a reference to identify the SE.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.PassportSAM.verify">
<code class="sig-name descname"><span class="pre">verify</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">PIN</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.PassportSAM.verify" title="Permalink to this definition"></a></dt>
<dd><p>Authenticate the card user. Check if he entered a valid PIN.
If the PIN is invalid decrement retry counter. If retry counter
equals zero, block the card until reset with correct PUK</p>
</dd></dl>
</dd></dl>
<dl class="py class">
<dt id="virtualsmartcard.cards.ePass.ePass_SE">
<em class="property"><span class="pre">class</span> </em><code class="sig-prename descclassname"><span class="pre">virtualsmartcard.cards.ePass.</span></code><code class="sig-name descname"><span class="pre">ePass_SE</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">MF</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">SAM</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">ssc</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE" title="Permalink to this definition"></a></dt>
<dd><p>Bases: <a class="reference internal" href="virtualsmartcard.SEutils.html#virtualsmartcard.SEutils.Security_Environment" title="virtualsmartcard.SEutils.Security_Environment"><code class="xref py py-class docutils literal notranslate"><span class="pre">virtualsmartcard.SEutils.Security_Environment</span></code></a></p>
<p>This class implements the Security Environment of the ICAO Passports. It
is required in order to use the send sequence counter for secure messaging.</p>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE._set_SE">
<code class="sig-name descname"><span class="pre">_set_SE</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE._set_SE" title="Permalink to this definition"></a></dt>
<dd><p>Manipulate the current Security Environment. P2 is the tag of a
control reference template, data contains control reference objects</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.compute_cryptographic_checksum">
<code class="sig-name descname"><span class="pre">compute_cryptographic_checksum</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.compute_cryptographic_checksum" title="Permalink to this definition"></a></dt>
<dd><p>Compute a cryptographic checksum (e.g. MAC) for the given data.
The ePass uses a Send Sequence Counter for MAC calculation</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.compute_digital_signature">
<code class="sig-name descname"><span class="pre">compute_digital_signature</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.compute_digital_signature" title="Permalink to this definition"></a></dt>
<dd><p>Compute a digital signature for the given data.
Algorithm and key are specified in the current SE</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>p1</strong> Must be 0x9E = Secure Messaging class for digital signatures</p></li>
<li><p><strong>p2</strong> Must be one of 0x9A, 0xAC, 0xBC. Indicates what kind of data
is included in the data field.</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.decipher">
<code class="sig-name descname"><span class="pre">decipher</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.decipher" title="Permalink to this definition"></a></dt>
<dd><p>Decipher data using key, algorithm, IV and Padding specified
by the current Security environment.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>raw data (no TLV coding). Padding is not removed!!!</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.encipher">
<code class="sig-name descname"><span class="pre">encipher</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.encipher" title="Permalink to this definition"></a></dt>
<dd><p>Encipher data using key, algorithm, IV and Padding specified
by the current Security environment.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>raw data (no TLV coding).</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.generate_public_key_pair">
<code class="sig-name descname"><span class="pre">generate_public_key_pair</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.generate_public_key_pair" title="Permalink to this definition"></a></dt>
<dd><p>The GENERATE PUBLIC-KEY PAIR command either initiates the generation
and storing of a key pair, i.e., a public key and a private key, in the
card, or accesses a key pair previously generated in the card.</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>p1</strong> should be 0x00 (generate new key)</p></li>
<li><p><strong>p2</strong> 00 (no information provided) or reference of the key to
be generated</p></li>
<li><p><strong>data</strong> One or more CRTs associated to the key generation if
P1-P2 different from 0000</p></li>
</ul>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.hash">
<code class="sig-name descname"><span class="pre">hash</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.hash" title="Permalink to this definition"></a></dt>
<dd><p>Hash the given data using the algorithm specified by the current
Security environment.</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>raw data (no TLV coding).</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.manage_security_environment">
<code class="sig-name descname"><span class="pre">manage_security_environment</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.manage_security_environment" title="Permalink to this definition"></a></dt>
<dd><p>This method is used to store, restore or erase Security Environments
or to manipulate the various parameters of the current SE.
P1 specifies the operation to perform, p2 is either the SEID for the
referred SE or the tag of a control reference template</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><p><strong>p1</strong> <p>Bitmask according to this table</p>
<table class="docutils align-default">
<colgroup>
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 4%" />
<col style="width: 71%" />
</colgroup>
<thead>
<tr class="row-odd"><th class="head"><p>b8</p></th>
<th class="head"><p>b7</p></th>
<th class="head"><p>b6</p></th>
<th class="head"><p>b5</p></th>
<th class="head"><p>b4</p></th>
<th class="head"><p>b3</p></th>
<th class="head"><p>b2</p></th>
<th class="head"><p>b1</p></th>
<th class="head"><p>Meaning</p></th>
</tr>
</thead>
<tbody>
<tr class="row-even"><td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>1</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>Secure messaging in command data field</p></td>
</tr>
<tr class="row-odd"><td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>1</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>Secure messaging in response data field</p></td>
</tr>
<tr class="row-even"><td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>1</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>Computation, decipherment, internal
authentication and key agreement</p></td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>Verification, encipherment, external
authentication and key agreement</p></td>
</tr>
<tr class="row-even"><td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><ul class="simple">
<li></li>
</ul>
</td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>1</p></td>
<td><p>SET</p></td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>1</p></td>
<td><p>0</p></td>
<td><p>STORE</p></td>
</tr>
<tr class="row-even"><td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>RESTORE</p></td>
</tr>
<tr class="row-odd"><td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>1</p></td>
<td><p>0</p></td>
<td><p>1</p></td>
<td><p>0</p></td>
<td><p>0</p></td>
<td><p>ERASE</p></td>
</tr>
</tbody>
</table>
</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.parse_SM_CAPDU">
<code class="sig-name descname"><span class="pre">parse_SM_CAPDU</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">CAPDU</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">authenticate_header</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.parse_SM_CAPDU" title="Permalink to this definition"></a></dt>
<dd><p>This methods parses a data field including Secure Messaging objects.
SM_header indicates whether or not the header of the message shall be
authenticated. It returns an unprotected command APDU</p>
<dl class="field-list simple">
<dt class="field-odd">Parameters</dt>
<dd class="field-odd"><ul class="simple">
<li><p><strong>CAPDU</strong> The protected CAPDU to be parsed</p></li>
<li><p><strong>authenticate_header</strong> Whether or not the header should be
included in authentication mechanisms</p></li>
</ul>
</dd>
<dt class="field-even">Returns</dt>
<dd class="field-even"><p>Unprotected command APDU</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.perform_security_operation">
<code class="sig-name descname"><span class="pre">perform_security_operation</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.perform_security_operation" title="Permalink to this definition"></a></dt>
<dd><p>In the end this command is nothing but a big switch for all the other
commands in ISO 7816-8. It will invoke the appropriate command and
return its result</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.protect_response">
<code class="sig-name descname"><span class="pre">protect_response</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">sw</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">result</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.protect_response" title="Permalink to this definition"></a></dt>
<dd><p>This method protects a response APDU using secure messaging mechanisms</p>
<dl class="field-list simple">
<dt class="field-odd">Returns</dt>
<dd class="field-odd"><p>the protected data and the SW bytes</p>
</dd>
</dl>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.verify_certificate">
<code class="sig-name descname"><span class="pre">verify_certificate</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.verify_certificate" title="Permalink to this definition"></a></dt>
<dd><p>Verify a certificate send by the terminal using the internal trust
anchors.
This method is currently not implemented.</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.verify_cryptographic_checksum">
<code class="sig-name descname"><span class="pre">verify_cryptographic_checksum</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.verify_cryptographic_checksum" title="Permalink to this definition"></a></dt>
<dd><p>Verify the cryptographic checksum contained in the data field.
Data field must contain a cryptographic checksum (tag 0x8E) and a plain
value (tag 0x80)</p>
</dd></dl>
<dl class="py method">
<dt id="virtualsmartcard.cards.ePass.ePass_SE.verify_digital_signature">
<code class="sig-name descname"><span class="pre">verify_digital_signature</span></code><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">p1</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">p2</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">data</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#virtualsmartcard.cards.ePass.ePass_SE.verify_digital_signature" title="Permalink to this definition"></a></dt>
<dd><p>Verify the digital signature contained in the data field. Data must
contain a data to sign (tag 0x9A, 0xAC or 0xBC) and a digital signature
(0x9E)</p>
</dd></dl>
</dd></dl>
</div>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<p class="pull-right">
<a href="#">Back to top</a>
</p>
<p>
&copy; Copyright 2009-2023 by Dominik Oepen and Frank Morgner.<br/>
</p>
</div>
</footer>
</body>
</html>