<html xmlns="http://www.w3.org/1999/xhtml" xmlns:html="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>
QuickStart – OpenSC
</title><style type="text/css">
@import url(trac.css);
</style></head><body><div id="content" class="wiki">
<div class="wikipage searchable">
<h1 id="QuickStartwithOpenSC">Quick Start with OpenSC</h1>
<p>
If you haven't already, please first take a look at our <a class="wiki" href="OverView.html" shape="rect">OverView</a> page, the
<a class="wiki" href="OperatingSystems.html" shape="rect">OperatingSystems</a> page and the <a class="wiki" href="CompilingInstalling.html" shape="rect">CompilingInstalling</a> page.
</p>
<h2 id="Beforewestart">Before we start…</h2>
<p>
A word of warning: these experiments can destroy your card (e.g. if we
have a bug. there is <strong>_NO WARRANTY_</strong> on opensc of any kind). Also
be sure to make notes of everything you do, <i>especially</i> the pin and
puk and so-pin and so-puk you set, as it is not possible to erase some
cards without these!
</p>
<h2 id="Installtherequiredmiddleware">Install the required middleware</h2>
<p>
Many card readers (or standalone USB tokens) use a nonstandard wire format for communicating between the computer and the device. You will need to get the corresponding (often proprietary) software up and running first. For USB tokens see the respective page on this Wiki (eg for <a class="wiki" href="AladdinEtokenPro.html" shape="rect">Aladdin EToken</a>, <a class="wiki" href="RainbowIkeyThree.html" shape="rect">Rainbow IKey 3000</a>). For card readers, you should get to the point where the LED turns on when you plug it into the USB socket.
</p>
<h2 id="InstallOpenSC">Install OpenSC</h2>
<p>
For Mac OS X, download and install <a href="http://www.opensc-project.org/sca/" shape="rect">SCA</a>.
</p>
<p>
For Windows, visit the <a href="http://www.opensc-project.org/build" shape="rect">build project</a>.
</p>
<p>
For Linux, either use your distribution's package manager or <a class="wiki" href="CompilingInstalling.html" shape="rect">install from source</a>.
</p>
<h2 id="TestOpenSC">Test OpenSC</h2>
<p>
First check if your smart card reader is found:
</p>
<pre class="wiki" xml:space="preserve">$ opensc-tool --list-readers
Readers known about:
Nr. Driver Name
0 openct Towitoko Chipdrive Micro
1 openct Aladdin eToken PRO
2 openct OpenCT reader (detached)
3 openct OpenCT reader (detached)
4 openct OpenCT reader (detached)
</pre><p>
You can see, openct claims five slots, but only two are used.
This is done to support hotplugging, those slots can be filled
later by additional readers you plugin via usb.
</p>
<p>
Next test is to see if your card is found. Every card has a so
called ATR ("Answer to reset"), a hex string used for identifying
the card type.
</p>
<pre class="wiki" xml:space="preserve">$ opensc-tool --reader 0 --atr
3b:e2:00:ff:c1:10:31:fe:55:c8:02:9c
</pre><p>
Lets see if that card is supported by OpenSC. If so, we should
know the name of the card:
</p>
<pre class="wiki" xml:space="preserve">$ opensc-tool --reader 0 --name
Cryptoflex 32K e-gate
</pre><p>
OpenSC has a small low level tool for exploring your smart card.
This is useful if you have a new card and want to look at it,
or check some details.
</p>
<pre class="wiki" xml:space="preserve">$ opensc-explorer
</pre><p>
However opensc-explorer only works with known cards and
even then: some cards don't have then required functionality,
for example no "ls" command.
</p>
<h1 id="Quickstartguidetoinitializingablankcard">Quick start guide to initializing a blank card</h1>
<p>
The best way to use all features of OpenSC is to start
with a blank card and initialize it with OpenSC. Make sure
your vendor sold you a real blank card, many vendors
also have pre-initialized cards, and those only work
with the vendors software, but not or only limited with
OpenSC.
</p>
<p>
<strong><i>'Warning: </i></strong>'before writing any data on the token please
read the smartcard os specific wiki pages as some smartcards cannot be
deleted once initialized.
</p>
<p>
You can add "-v" to all of these commands, to get a more verbose
output. Adding "-v" more than once will enable debugging or increase
the debugging level.
</p>
<p>
First you need to create the basic structure. At this step you are
asked to enter a "security office" pin. Only with this pin you can
alter the card, but that pin is not needed to use the keys.
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-init --create-pkcs15
New Security Officer PIN (Optional - press return for no PIN).
Please enter Security Officer PIN:
Please type again to verify:
Unblock Code for New User PIN (Optional - press return for no PIN).
Please enter User unblocking PIN (PUK):
Please type again to verify:
</pre><p>
Next step is to create a user and a pin. That pin is needed for
using the keys we will create later.
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-init --store-pin --auth-id 01 --label "Andreas Jellinghaus"
New User PIN.
Please enter User PIN:
Please type again to verify:
Unblock Code for New User PIN (Optional - press return for no PIN).
Please enter User unblocking PIN (PUK):
Please type again to verify:
Security officer PIN required.
Please enter Security officer PIN:
</pre><p>
Now create a key. Both pins are needed for this.
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-init --generate-key rsa/1024 --auth-id 01
Security officer PIN required.
Please enter Security officer PIN:
User PIN required.
Please enter User PIN:
Security officer PIN required.
Please enter Security officer PIN:
</pre><p>
You can list the keys on the token with
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-tool --list-keys
Private RSA Key [Private Key]
Com. Flags : 3
Usage : [0x4], sign
Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
ModLength : 1024
Key ref : 16
Native : yes
Path : 3F005015
Auth ID : 01
ID : 45
</pre><h2 id="TestingusingOpenSSL">Testing using OpenSSL</h2>
<p>
If you followed thus far, your token is now fitted with a private RSA key that it generated itself and never divulged to anybody (not even the host computer). Assuming <a href="http://www.opensc-project.org/engine_pkcs11/" shape="rect">engine_pkcs11</a> is installed, we can use this key and openssl to create
a self signed certificate, still without divulging the key; the necessary cryptographic computations will occur on-token.
</p>
<p>
Let's start the OpenSSL interactive shell and load the <a href="http://www.opensc-project.org/engine_pkcs11/" shape="rect">engine pkcs11</a> so that OpenSSL can ask the token to do the crypto (as opposed to doing it from your computer's CPU).
</p>
<ul><li><strong>Linux</strong>: open a terminal and type this (skipping the prompts):
<pre class="wiki" xml:space="preserve">$ openssl
OpenSSL> engine dynamic -pre SO_PATH:/usr/lib/engines/engine_pkcs11.so -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:opensc-pkcs11.so
</pre></li></ul><ul><li><strong>Mac OS X</strong>: open a terminal and type this (skipping the prompts):
<pre class="wiki" xml:space="preserve">$ /Library/OpenSC/bin/openssl
OpenSSL> engine dynamic -pre SO_PATH:/Library/OpenSC/lib/engines/engine_pkcs11.so -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/usr/lib/opensc-pkcs11.so
</pre></li></ul><p>
In both cases, OpenSSL should respond with something like
</p>
<pre class="wiki" xml:space="preserve">(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/usr/lib/engines/engine_pkcs11.so
[Success]: ID:pkcs11
[Success]: LIST_ADD:1
[Success]: LOAD
Loaded: (pkcs11) pkcs11 engine
OpenSSL>
</pre><p>
It is important to enter the whole long command in one single command
line. I usually copy&paste the command, to make sure I don't mistype
anything.
</p>
<p>
Staying at the OpenSSL prompt, now type:
</p>
<pre class="wiki" xml:space="preserve">OpenSSL> req -engine pkcs11 -new -key id_45 -keyform engine -x509 -out cert.pem -text
SmartCard PIN:
You are about to be asked to enter information that will be incorporated
into your certificate request.
What you are about to enter is what is called a Distinguished Name or a DN.
There are quite a few fields but you can leave some blank
For some fields there will be a default value,
If you enter '.', the field will be left blank.
-----
Country Name (2 letter code) [AU]:.
State or Province Name (full name) [Some-State]:.
Locality Name (eg, city) []:.
Organization Name (eg, company) [Internet Widgits Pty Ltd]:.
Organizational Unit Name (eg, section) []:.
Common Name (eg, YOUR name) []:Andreas Jellinghaus
Email Address []:aj@dungeon.inka.de
Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:
OpenSSL>
</pre><p>
This creates a signed certificate as file <tt>cert.pem</tt> (again, without divulging the private key). You can verify that it is indeed self-signed (the private key is not required for this): exit OpenSSL and type
</p>
<pre class="wiki" xml:space="preserve">$ openssl verify -CAfile cert.pem cert.pem
cert.pem: OK
</pre><p>
If instead you remove the "-x509" flag in the <tt>req</tt> OpenSSL command, you get a certificate signing request. Send it to the CA, wait till you get it back, signed, and
proceed.
</p>
<p>
Now we can store the certificate side by side with the key on the
token, as a piece of public (but read-only) data. It is important to
save the certificate under the same ID as the key, so that applications wanting to use that certificate on your behalf can find the private key as well. You can get a list
of all keys and their details (including the ID) with:
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-tool --list-keys
Private RSA Key [Private Key]
Com. Flags : 3
Usage : [0x4], sign
Access Flags: [0x1D], sensitive, alwaysSensitive, neverExtract, local
ModLength : 1024
Key ref : 16
Native : yes
Path : 3F005015
Auth ID : 01
ID : 45
</pre><p>
So lets store the certificate that we created:
</p>
<pre class="wiki" xml:space="preserve">$ pkcs15-init --store-certificate cert.pem --auth-id 01 --id 45 --format pem
Security officer PIN required.
Please enter Security officer PIN:
</pre><p>
Now we are ready to go. If you want to add more certificates (e.g. the root
certificate of the CA that signed your key, or some intermediate certificates
in the chain to the root CA) simply put those into pem files, and add them
to id 46, 47 and so on. You don't need the private key for these obviously.
</p>
<h1 id="Nowwhat">Now what?</h1>
<p>
You probably want to make your token work with other applications than
<tt>pkcs15-init</tt> and OpenSSL: see <a class="wiki" href="WikiStart#ApplicationSupport.html" shape="rect">Application Support</a> on the main page.
</p>
<p>
If you want to login to your computer with your smart card or crypto
token, please note that OpenSC 0.10 does not include the pam module
and the openssl engine any more. We suggest you install
<a href="http://www.opensc-project.org/libp11/" shape="rect">libp11</a>,
<a href="http://www.opensc-project.org/engine_pkcs11/" shape="rect">engine_pkcs11</a> and one
of <a href="http://www.opensc-project.org/pam_p11/" shape="rect">pam_p11</a> (a simple
authentication module) or <a href="http://www.opensc-project.org/pam_pkcs11/" shape="rect">pam_pkcs11</a> (a full featured authentication module).
</p>
<h1 id="Links">Links</h1>
<ul><li><a class="ext-link" href="http://daniel.benoy.name/?p=76" shape="rect"><span class="icon"> </span>eToken PRO initial setup tutorial</a>
</li></ul>
</div>
</div><div class="footer"><hr></hr><p><a href="index.html">Back to Index</a></p></div></body></html>
