<htmlxmlns="http://www.w3.org/1999/xhtml"><head><metahttp-equiv="Content-Type"content="text/html; charset=UTF-8"/><title>OpenSC Manual</title><linkrel="stylesheet"href="opensc.css"type="text/css"/><metaname="generator"content="DocBook XSL Stylesheets V1.60.1"/></head><body><divclass="book"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h1class="title"><aid="id2755323"></a>OpenSC Manual</h1></div><div><divclass="author"><h3class="author"></h3></div></div></div><div></div><hr/></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt>1. <ahref="#id2752120">Introduction</a></dt><dt>2. <ahref="#id2752137">Authors and Contributors</a></dt><dd><dl><dt><ahref="#id2796698">Thanks</a></dt></dl></dd><dt>3. <ahref="#id2796764">Copyright and License</a></dt><dt>4. <ahref="#id2796789">Building and Installing libopensc</a></dt><dd><dl><dt><ahref="#id2796806">Windows </a></dt><dt><ahref="#id2796854">Windows with OpenSSL</a></dt></dl></dd><dt>5. <ahref="#id2796932">Status</a></dt><dd><dl><dt><ahref="#id2796937">Card Status</a></dt><dt><ahref="#id2797072">Windows</a></dt><dt><ahref="#id2797088">PKCS#11 Module in Netscape and Mozilla</a></dt></dl></dd><dt>6. <ahref="#id2797132">Using OpenSC</a></dt><dd><dl><dt><ahref="#id2797139">OpenSC and Netscape</a></dt><dt><ahref="#id2797204">OpenSC and Mozilla</a></dt><dt><ahref="#id2797252">OpenSC and OpenSSL</a></dt><dt><ahref="#id2797448">OpenSC and OpenSSH</a></dt><dt><ahref="#id2797558">Pluggable Authentication Module</a></dt><dd><dl><dt><ahref="#id2797728">eid based authentication</a></dt><dt><ahref="#id2797772">ldap based authentication</a></dt></dl></dd></dl></dd><dt>7. <ahref="#id2797942">The OpenSC PKCS11 library</a></dt><dd><dl><dt><ahref="#id2797949">What is PKCS11</a></dt><dt><ahref="#id2798015">Virtual slots</a></dt></dl></dd><dt>8. <ahref="#id2798125">What needs to be done</a></dt><dd><dl><dt><ahref="#id2798158">Windows</a></dt></dl></dd><dt>9. <ahref="#id2798176">Troubleshooting</a></dt><dt>10. <ahref="#id2798191">Resources</a></dt><dt>11. <ahref="#id2798224">Signer</a></dt><dd><dl><dt><ahref="#id2798237">Building and Installing libopensc</a></dt></dl></dd><dt>12. <ahref="#id2798279">A few hints on docbook documents</a></dt></dl></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2752120"></a>Chapter1.Introduction</h2></div></div><div></div></div><p>
</p></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2752137"></a>Chapter2.Authors and Contributors</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2796698">Thanks</a></dt></dl></div><p>
Juha Yrjölä <ttclass="email"><<ahref="mailto:juha.yrjola@iki.fi">juha.yrjola@iki.fi</a>></tt></li></ul></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2796698"></a>Thanks</h2></div></div><div></div></div><p>
Geoff Thrope <ttclass="email"><<ahref="mailto:geoff@geoffthorpe.net">geoff@geoffthorpe.net</a>></tt></li></ul></div></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2796764"></a>Chapter3.Copyright and License</h2></div></div><div></div></div><tableborder="0"bgcolor="#E0E0E0"><tr><td><preclass="screen">
</pre></td></tr></table></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2796789"></a>Chapter4.Building and Installing libopensc</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2796806">Windows </a></dt><dt><ahref="#id2796854">Windows with OpenSSL</a></dt></dl></div><p>
</li></ol></div></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2796854"></a>Windows with OpenSSL</h2></div></div><div></div></div><p>
</p></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2796932"></a>Chapter5.Status</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2796937">Card Status</a></dt><dt><ahref="#id2797072">Windows</a></dt><dt><ahref="#id2797088">PKCS#11 Module in Netscape and Mozilla</a></dt></dl></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2796937"></a>Card Status</h2></div></div><div></div></div><divclass="variablelist"><dl><dt><spanclass="term">CryptoFlex</span></dt><dd><p>
</p></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797088"></a>PKCS#11 Module in Netscape and Mozilla</h2></div></div><div></div></div><p>
</p></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2797132"></a>Chapter6.Using OpenSC</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2797139">OpenSC and Netscape</a></dt><dt><ahref="#id2797204">OpenSC and Mozilla</a></dt><dt><ahref="#id2797252">OpenSC and OpenSSL</a></dt><dt><ahref="#id2797448">OpenSC and OpenSSH</a></dt><dt><ahref="#id2797558">Pluggable Authentication Module</a></dt><dd><dl><dt><ahref="#id2797728">eid based authentication</a></dt><dt><ahref="#id2797772">ldap based authentication</a></dt></dl></dd></dl></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797139"></a>OpenSC and Netscape</h2></div></div><div></div></div><divclass="procedure"><oltype="1"><li>
</p></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797204"></a>OpenSC and Mozilla</h2></div></div><div></div></div><divclass="procedure"><oltype="1"><li>
</li></ol></div></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797252"></a>OpenSC and OpenSSL</h2></div></div><div></div></div><p>
<iclass="replaceable"><tt>key</tt></i> has the format [slot_<slotNr>][-][id_<keyID>], in which
</p><divclass="itemizedlist"><ultype="disc"><li>
the optional slotNr indicates which pkcs11 slot to take
(starting from 0, which is also the default)
</li><li>
keyID is the key ID in hex notation
</li></ul></div><p>
Examples:
</p><divclass="itemizedlist"><ultype="disc"><li>
id_45 => private key with ID = 0x45 in the first 'suited' slot
</li><li>
slot_2-id_46 => private key with ID = 0x46 in the third slot
</li></ul></div><p>
</p><p>
For Windows, only the pkcs11 engine (not the opensc engine) has been ported;
use "engine_pkcs11" instead of "engine_pkcs11.so".
</p></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797448"></a>OpenSC and OpenSSH</h2></div></div><div></div></div><p>
</p><divclass="variablelist"><dl><dt><spanclass="term">debug</span></dt><dd>log more debugging info</dd><dt><spanclass="term">audit</span></dt><dd>a little more extreme than debug</dd><dt><spanclass="term">use_first_pass</span></dt><dd>don't prompt the user for passwords, take them from PAM_ items insteat</dd><dt><spanclass="term">try_first_pass</span></dt><dd>don't prompt the user for passwords unless PAM_(OLD)AUTHTOK in unsed</dd><dt><spanclass="term">use_authtok</span></dt><dd>require PAM_AUTHTOK set, use it, fail otherwise</dd><dt><spanclass="term">set_pass</span></dt><dd>set the PAM_ item swith the passwords used by this module</dd><dt><spanclass="term">nodelay</span></dt><dd>used to prevent failed authentication resulting in a delay of about 1 second.</dd><dt><spanclass="term">auth_method=X</span></dt><dd>choose either pkcs15-ldap or pkcs15-eid authentication. pkcs15-eid is the default.</dd></dl></div><p>
</p><p>
Generic options:
</p><divclass="variablelist"><dl><dt><spanclass="term">-h</span></dt><dd>Show help</dd><dt><spanclass="term">-r reader</span></dt><dd>Reader name (FIXME: not number?)</dd></dl></div><p>
</p><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h3class="title"><aid="id2797728"></a>eid based authentication</h3></div></div><div></div></div><p>
</p></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h3class="title"><aid="id2797772"></a>ldap based authentication</h3></div></div><div></div></div><p>
</p><divclass="variablelist"><dl><dt><spanclass="term">-L ldap.conf</span></dt><dd>Configuration file to load</dd><dt><spanclass="term">-A entry</span></dt><dd>Add new entry</dd><dt><spanclass="term">-E entry</span></dt><dd>Set current entry</dd><dt><spanclass="term">-H hostname</span></dt><dd>hostname of ldap server</dd><dt><spanclass="term">-P port</span></dt><dd>port or ldap server</dd><dt><spanclass="term">-S scope</span></dt><dd>scope of ldap server</dd><dt><spanclass="term">-b binddn</span></dt><dd>binddn for ldap connection</dd><dt><spanclass="term">-p passwd</span></dt><dd>password for ldap bind</dd><dt><spanclass="term">-B base</span></dt><dd>base for ldap bind</dd><dt><spanclass="term">-a attributes</span></dt><dd>attributes to fetch</dd><dt><spanclass="term">-f filter</span></dt><dd>filter in ldap search</dd></dl></div><p>
</p></div></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2797942"></a>Chapter7.The OpenSC PKCS11 library</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2797949">What is PKCS11</a></dt><dt><ahref="#id2798015">Virtual slots</a></dt></dl></div><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2797949"></a>What is PKCS11</h2></div></div><div></div></div><p>
PKCS11 is a standard API for accessing cryptographic tokens
such as smart cards, Hardware Security Modules, ...
It contains functions like C_GetSlotList(), C_OpenSession(),
C_FindObjects(), C_Login(), C_Decrypt(), ...
</p><p>
Some core concepts of pkcs11 are:
</p><divclass="itemizedlist"><ultype="disc"><li>
slot: the place in which a smart card can be put. Usually this
corresponds with a card reader (but: see below, Virtual slots).
</li><li>
token: the thing that is put in a slot. Usually this corresponds
with a smart card (but: see below, virtual slots).
</li><li>
object: a key, a certificate, some data, ... Is either a token
object (if it resides on the card) or a session object (if it
doesn't reside on the card, e.g. a certificate given to the
pkcs11 library to do a verification).
</li><li>
session: before you can do anything with a token, you have to
open a session on it.
</li><li>
operation: a signature, decryption, digest, ... operation, that
can consist of multiple function calls. Example: C_SignInit(),
C_SignUpdate(), C_SignFinal(); here the first function starts
the operation, the third one ends it. Only one operation can be
done in the same session, but multiple sessions can be opened
Per token, only 2 PINs can be given: the SO (Security Officer) PIN
and the user PIN. However, smart cards can have more than 1 user
PIN.
A way to this solve problem is to have multiple 'virtual' slots,
as explained in appendix D of the pkcs11 standard. So per physical
reader, you have a number of virtual slots. If you insert a card
in the reader, a token will appear in all the virtual slots,
and each token will contain 1 PIN along with the private keys
it protects and certificates corresponding to those private keys.
</p><p>
Because OpenSC supports multiple cards, it is not known in advance
how many PINs a smart card will have. Therefore, a default number
of 4 virtual slots is used. You can change this default in the
pkcs11 section of opensc.conf: num_slots.
</p><p>
Opensc implements the following behaviour: for each PIN, its
private keys and corresponding certs, there is 1 virtual slot
allocated. If there are any objects left, they are put in the
next free virtual slot. And if there are some virtual slots left,
an 'empty' token is 'put' in them; on this empty token a PIN and
data can then be put. If you find this too confusing, you
can hide empty tokens with the hide_empty_tokens option in
the config file.
</p><p>
Example:
Take a card with 2 PINs. Each PIN protects a private key and
each private key has a corresponding cert chain. And then there
are 3 other roots certs that have nothing to do with the other
data.
Now if num_slots = 4, hide_empty_tokens = false; and if you put
the card your second card reader, you'll get the following:
</p><divclass="itemizedlist"><ultype="disc"><li>
token in slot 4: PIN 1, key 1, cert chain 1
</li><li>
token in slot 5: PIN 2, key 2, cert chain 2
</li><li>
token in slot 6: the 3 other root certs
</li><li>
token in slot 7: no data
</li></ul></div><p>
If hide_empty_tokens would have been true, slot 7 wouldn't show
a token.
</p><p>
Note: if in the example the 2 cert chain would have common
certificates, those certificates would appear in the tokens
in slots 4 and 5. (Which would cause a problem if those
certs were deleted, this hasn't been solved yet in OpenSC).
</p><p>
Another good-to-know: the number of virtual slots has been
hard-coded (it is 8 at the moment). So if num_slots = 4,
only the first 2 readers will be visible. Or if you'd put
num_slots to 3, the first 2 readers will have 3 virtual
slots and the third reader will have 2.
</p></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2798125"></a>Chapter8.What needs to be done</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2798158">Windows</a></dt></dl></div><tableborder="0"bgcolor="#E0E0E0"><tr><td><preclass="screen">
</p></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2798224"></a>Chapter11.Signer</h2></div></div><div></div></div><divclass="toc"><p><b>Table of Contents</b></p><dl><dt><ahref="#id2798237">Building and Installing libopensc</a></dt></dl></div><p>
</p><divclass="section"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"style="clear: both"><aid="id2798237"></a>Building and Installing libopensc</h2></div></div><div></div></div><p>
</p></div></div><divclass="chapter"lang="en"xml:lang="en"><divclass="titlepage"><div><div><h2class="title"><aid="id2798279"></a>Chapter12.A few hints on docbook documents</h2></div></div><div></div></div><p>
with a greate introduction on how to create a document,
how to convert it, where to get the software, tools
and everything. It you a fast road to editing this
document, look at this book.
</p><p>
THis document might be ugly. If you know html,
please help us to improve it. Some stuff can
be tuned in the xsl stylesheet (see <ahref="http://docbook.sourceforge.net/release/xsl/current/doc/html/"target="_top">Reference for the HTML stylesheet parameters</a>), but most stuff can be improved via CSS