1368 lines
38 KiB
XML
1368 lines
38 KiB
XML
<?xml version="1.0" encoding="utf-8" ?>
|
|
<book ns="http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" id="opensc">
|
|
<title>OpenSC Manual</title>
|
|
<bookinfo>
|
|
<author>
|
|
<name>OpenSC Development Team</name>
|
|
<email>opensc-devel@opensc.org</email>
|
|
</author>
|
|
</bookinfo>
|
|
|
|
<toc />
|
|
|
|
<chapter id="opensc.intro">
|
|
<title>Introduction</title>
|
|
|
|
<para>
|
|
libopensc is a library for accessing SmartCard devices
|
|
using PC/SC Lite middleware package. It is also the
|
|
core library of the OpenSC project. Basic
|
|
functionality (e.g. SELECT FILE, READ BINARY) should
|
|
work on any ISO 7816-4 compatible SmartCard. Encryption
|
|
and decryption using private keys on the SmartCard is
|
|
at the moment possible only with PKCS#15 compatible
|
|
cards, such as the FINEID (Finnish Electronic IDentity)
|
|
card manufactured by Setec.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.authors">
|
|
<title>Authors and Contributors</title>
|
|
|
|
<para>
|
|
Here is a list of all Authors and Contributors
|
|
of OpenSC in alphabetical order:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
Robert Bihlmeyer <email>robbe@orcus.priv.at</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Stef Hoeben <email>Hoeben.S@Zetes.com</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Andreas Jellinghaus <email>aj@dungeon.inka.de</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Olaf Kirch <email>okir@suse.de</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Nils Larsch <email>larsch@trustcenter.de</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Kevin Stefanik <email>kstef@mtppi.org</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Antti Tapaninen <email>aet@cc.hut.fi</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Timo Teräs <email>timo.teras@iki.fi</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Juha Yrjölä <email>juha.yrjola@iki.fi</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Jörn Zukowski <email>zukowski@trustcenter.de</email>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="opensc.authors.thanks">
|
|
<title>Thanks</title>
|
|
|
|
<para>
|
|
The following people provided inspiration,
|
|
moral support and/or valuable information
|
|
during the development of OpenSC:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
Antti Partanen
|
|
<email>antti.partanen@vrk.intermin.fi</email>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
David Corcoran <email>corcoran@linuxnet.com</email>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<para>
|
|
OpenSC did neither invent the wheel nor
|
|
write all code from scratch. We could
|
|
reuse some code from other projects
|
|
mostly to interface with these projects.
|
|
Thanks to the original authors:
|
|
</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
Matthias Brüstle
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Markus Friedl
|
|
</listitem>
|
|
|
|
<listitem>
|
|
Geoff Thrope <email>geoff@geoffthorpe.net</email>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.license">
|
|
<title>Copyright and License</title>
|
|
|
|
<screen>
|
|
OpenSC smart card library
|
|
Copyright (C) OpenSC developers
|
|
|
|
This library is free software; you can redistribute it and/or
|
|
modify it under the terms of the GNU Lesser General Public
|
|
License as published by the Free Software Foundation; either
|
|
version 2.1 of the License, or (at your option) any later version.
|
|
|
|
This library is distributed in the hope that it will be useful,
|
|
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
Lesser General Public License for more details.
|
|
|
|
You should have received a copy of the GNU Lesser General Public
|
|
License along with this library; if not, write to the Free Software
|
|
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
|
|
</screen>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.overview">
|
|
<title>Overview</title>
|
|
|
|
<para>
|
|
OpenSC is a large toolkit. The main building
|
|
block is the opensc library. It has three layers
|
|
of code, each with several drivers in it.
|
|
Other libraries are the pkcs11 module,
|
|
a pam module, two engines for openssl.
|
|
In addition there are several tools to test and
|
|
use these tools and libraries.
|
|
</para>
|
|
|
|
<para>
|
|
Purpose of this chapter is to give an overview
|
|
of the inner workings of the opensc library,
|
|
to give a short presentation what the other
|
|
libraries do, and finaly what the opensc toolchest
|
|
has to offer. Each tool has it's own man page,
|
|
each library it's own section in this document.
|
|
</para>
|
|
|
|
<section id="opensc.overview.layers">
|
|
<title>Layers in libopensc</title>
|
|
|
|
<para>
|
|
libopensc is the basic library used by
|
|
everthing else. It offer basic
|
|
functionality like talking to smart
|
|
cards, but also advances functions
|
|
like generating rsa keys on a smart card.
|
|
</para>
|
|
|
|
<para>
|
|
libopensc has several layers of functionality,
|
|
each implemented by one or several drivers.
|
|
The layers are:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>reader</term>
|
|
<listitem>
|
|
OpenSC needs some way to talk to
|
|
smart card readers and cards in
|
|
the smart card readers. Different
|
|
software can be used for that purpose,
|
|
each software has it's own reader
|
|
module so OpenSC can use that software.
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>card</term>
|
|
<listitem>
|
|
In a perfect world all smart cards
|
|
would implement ISO 7816 standard,
|
|
and thus accept the same commands
|
|
and give the same answers. Unfortunatly
|
|
most cards have their own commands,
|
|
syntax and responses. The card modules
|
|
in libopensc implement these different
|
|
commands.
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>pkcs15init</term>
|
|
<listitem>
|
|
Smart cards usualy have a file system.
|
|
To store or create keys or certiticates
|
|
on a smart card one needs to format
|
|
the card, create directories and objects
|
|
and set permissions in a secure way.
|
|
Not only are the commands to do this
|
|
different from card to card, also the
|
|
security model is often very different.
|
|
These pkcs15init modules implement
|
|
these differences.
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>pkcs15 framework</term>
|
|
<listitem>
|
|
<para>
|
|
PKCS#15 is the standard on how to
|
|
store certificates and keys on a
|
|
smart card or crypto token. But many
|
|
vendors have their own proprietory
|
|
mechanism for storing these
|
|
informations, for example in different
|
|
directories. OpenSC implements
|
|
the PKCS#15 standard, but there is
|
|
also an emulation module for a
|
|
slightly incompatible storage mechanism
|
|
in the works.</para>
|
|
|
|
<para>
|
|
It should be possible to implement a
|
|
completely differennt framework
|
|
for compatiblity with a non
|
|
pkcs#15 way of storing and accessing
|
|
keys and certificates.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="opensc.overview.readers">
|
|
<title>The reader layer</title>
|
|
|
|
<para>
|
|
PC/SC-Lite is well known as smart card
|
|
middleware. It interacts with drivers for
|
|
the smart card readers on the buttom,
|
|
and with smart card applications on the top.
|
|
OpenSC can use PC/SC-Lite via the pcsc
|
|
reader module, but also supports a number
|
|
of alternatives.
|
|
</para>
|
|
|
|
<para>
|
|
PC/SC is a standard with interfaces betweens
|
|
applications, a resource manager and drivers
|
|
for smart card readers. This standard is
|
|
very popular on the Windows operating System.
|
|
The documents are available from the
|
|
<ulink url="http://www.pcscworkgroup.com/" />.
|
|
</para>
|
|
|
|
<para>
|
|
PC/SC-Lite is an implementation of the
|
|
PC/SC standard for linux, Unix, Mac OS X
|
|
and Windows by David Corcoran
|
|
<email>corcoran@linuxnet.com</email>. The
|
|
software is available with full source code and
|
|
available for free. To download the software,
|
|
please visit the website of the Movement
|
|
for the use of smart cards in a linux
|
|
environment (M.U.S.C.L.E.) at <ulink
|
|
url="http://www.linuxnet.com/" />.
|
|
</para>
|
|
|
|
<para>
|
|
To install OpenSC with support for PC/SC-Lite,
|
|
please install PC/SC-Lite first. Then configure
|
|
OpenSC to use PC/SC-Lite and specify the
|
|
location where PC/SC-Lite is installed like
|
|
this:
|
|
<screen>
|
|
$ cd opensc-0.8.0
|
|
$ ./configure --with-pcsclite=/path/to/pcsclite
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
OpenCT is a new framework for accessing
|
|
smart cards, card readers and card terminals.
|
|
It was written from scratch, already includes
|
|
all drivers, and is very lightwight. OpenCT
|
|
is available for linux, but if you want to
|
|
use it on other Unix or BSD operating systems,
|
|
please ask for help on the opensc-devel mailing
|
|
list.
|
|
</para>
|
|
|
|
<para>
|
|
OpenCT is open source software. As such
|
|
it is availble with full source code for
|
|
free. OpenCT is a software companion
|
|
to OpenSC and the prefered way of accessing
|
|
smart cards under linux. OpenCT is available
|
|
from the OpenSC website <ulink
|
|
url="http://www.opensc.org/" /> and
|
|
questions go to the
|
|
<email>opensc-devel@opensc.org</email> mailing
|
|
list.
|
|
</para>
|
|
|
|
<para>
|
|
To compile OpenSC with support for OpenCT,
|
|
please install OpenCT first. Documentation
|
|
on OpenCT is part of the source code, and
|
|
also available online at <ulink
|
|
url="http://www.opensc.org/files/doc/openct.html" />.
|
|
Then configure OpenSC to use OpenCT and specify
|
|
the location where OpenCT is installed like
|
|
this:
|
|
</para>
|
|
|
|
<para>
|
|
Usbtoken is a small driver for usb crypto
|
|
devices only. It does not need any other helper
|
|
software and is included in OpenSC for
|
|
convinience. However Usbtoken is deprecated,
|
|
the new OpenCT software is now the recommended
|
|
way to access usb crypto tokens. Usbtoken
|
|
is no longer activly developed, but bugs are
|
|
still fixed and help is provided on the
|
|
OpenSC mailing list at
|
|
<email>opensc-devel@opensc.org</email>.
|
|
</para>
|
|
|
|
<para>
|
|
If you still want to use OpenSC with Usbtoken,
|
|
please configure OpenSC like this:
|
|
<screen>
|
|
$ cd opensc-0.8.0
|
|
$ ./configure --enable-usbtoken
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
Documentation on Usbtoken is in the file
|
|
<ulink url="usbtoken.html" />.
|
|
</para>
|
|
|
|
<para>
|
|
CT-API is a standard format for
|
|
drivers for smart card readers. It was
|
|
invented in the eighties for DOS applications
|
|
and is maybe not very fit for todays
|
|
multiuser multitasking applications.
|
|
However CT-API is still quite popular,
|
|
and many smart card readers have drivers
|
|
in CT-API format even for linux. It is
|
|
recommended to use these drivers if
|
|
the PC/SC-Lite middleware described above.
|
|
</para>
|
|
|
|
<para>
|
|
But OpenSC can also use CT-API drivers
|
|
directly. This is meant for debugging mostly
|
|
and not recommended in a multi user or
|
|
multi application environment.
|
|
</para>
|
|
|
|
<para>
|
|
OpenSC includes always support for drivers
|
|
in CT-API format, you don't need to do
|
|
anything special for compiling.
|
|
See the <filename>opensc.conf</filename>
|
|
configuration file on how to configure
|
|
an CT-API driver with OpenSC.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
|
|
</chapter>
|
|
|
|
<chapter id="opensc.install">
|
|
<title>Building and Installing libopensc</title>
|
|
|
|
<para>
|
|
See the INSTALL file for instructions. If you are
|
|
using the CVS version, you have to run the 'bootstrap'
|
|
script before running configure. Please note, that for
|
|
bootstrap to work, you have to have the correct
|
|
versions of Autoconf, Automake and Libtool installed.
|
|
</para>
|
|
|
|
<section id="opensc.install.windows">
|
|
<title>Windows </title>
|
|
|
|
<para>
|
|
Type "nmake -f makefile.mak" in the opensc\
|
|
dir to compile.
|
|
</para>
|
|
|
|
<para>
|
|
You need also perl and flex installed for the
|
|
compile process to complete succesfully.
|
|
</para>
|
|
|
|
<para>
|
|
No installation script has been provided, so
|
|
you have to do this manually:
|
|
</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
Copy opensc.conf to your Windows
|
|
directory (usually C:\WINDOWS or
|
|
C:\WINNT). This is optional.
|
|
</step>
|
|
|
|
<step>
|
|
Copy opensc.dll and opensc-pkcs11.dll
|
|
to your path.
|
|
</step>
|
|
|
|
<step>
|
|
If you want to use pkcs15-init.exe,
|
|
make sure the *.profile files in the
|
|
pkcs15-init\ dir are in the same
|
|
directory as pkcs15-init.exe.
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
|
|
<section id="opensc.install.windowsopenssl">
|
|
<title>Windows with OpenSSL</title>
|
|
|
|
<para>
|
|
This adds extended functionality. E.g. the
|
|
pkcs15-init tool, pkcs11 hash mechanisms and
|
|
more pkcs11 signature mechs.
|
|
</para>
|
|
|
|
<procedure>
|
|
<step>
|
|
download and compile the openssl
|
|
sources from <ulink url="http://www.openssl.org/source/" />
|
|
</step>
|
|
|
|
<step>
|
|
Add the inc32\ dir to your include
|
|
path, the out32dll\ to your lib path
|
|
and your executable path
|
|
<screen>
|
|
set include=%include%;.....\inc32
|
|
set lib=%lib%;.....\out32dll
|
|
set path=%path%;....\out32dll
|
|
</screen>
|
|
</step>
|
|
|
|
<step>
|
|
In src/tools/Makefile.mak uncomment
|
|
pkcs15-init.exe in the "TARGETS" line
|
|
(optionally) and add libeay32.lib (and
|
|
gdi32.lib) to the "link" line
|
|
</step>
|
|
|
|
<step>
|
|
In src/libopensc/Makefile.mak add
|
|
libeay32.lib (and gdi32.lib) to the
|
|
"link" line
|
|
</step>
|
|
|
|
<step>
|
|
In src/pkcs11/Makefile.mak add
|
|
libeay32.lib (and gdi32.lib) to the
|
|
"link" line
|
|
</step>
|
|
|
|
<step>
|
|
In win32/Make.rules.mak add
|
|
/DHAVE_OPENSSL to the "COPTS" line
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>
|
|
To add the OpenSSL code to the DLLs (so you
|
|
won't need libeay32.dll anymore): statically
|
|
compile OpenSSL and add gdi32.lib next to
|
|
libeay32.lib in the 3 Makefile.mak files above.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</chapter>
|
|
|
|
<chapter id="opensc.status">
|
|
<title>Status</title>
|
|
|
|
|
|
<section id="opensc.status.cards">
|
|
<title>Card Status</title>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>CryptoFlex</term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
Support signing/decrypting, and initialization
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Gemplus PK 4K, 8K, 16K</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Support signing/decrypting, and initialization.
|
|
</para>
|
|
|
|
<para>
|
|
NOTE: You will not be able to initialize a
|
|
GemSafe cards - these card already have been
|
|
personalized by Gemplus, and you cannot erase
|
|
them or create new key files on them.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Aladdin eToken PRO</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Support signing/decrypting, and initialization.
|
|
</para>
|
|
|
|
<para>
|
|
NOTE: CardOS only supports keys for
|
|
decryption or signing, but not both.
|
|
If you create/store keys with "--split-keys"
|
|
OpenSC will work around this limitation.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Eutron CryptoIdendity IT-SEC</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Support signing/decrypting, and initialization.
|
|
</para>
|
|
|
|
<para>
|
|
NOTE: CardOS only supports keys for
|
|
decryption or signing, but not both.
|
|
If you create/store keys with "--split-keys"
|
|
OpenSC will work around this limitation.
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Micardo</term>
|
|
<listitem>
|
|
|
|
<para>
|
|
Supported - need to fill in the details
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Miocos</term>
|
|
<listitem>
|
|
|
|
<para>
|
|
Supported - need to fill in the details
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Setcos</term>
|
|
<listitem>
|
|
|
|
<para>
|
|
Supported - need to fill in the details
|
|
</para>
|
|
</listitem></varlistentry>
|
|
|
|
<varlistentry><term>Tcos</term>
|
|
<listitem>
|
|
|
|
<para>
|
|
Supported - need to fill in the details
|
|
</para>
|
|
</listitem></varlistentry>
|
|
</variablelist>
|
|
</section>
|
|
|
|
<section id="opensc.status.windows">
|
|
<title>Windows</title>
|
|
|
|
<para>
|
|
At the moment only libopensc.dll and
|
|
opensc-pkcs11.dll, and most executables in the
|
|
tools\ and tests\ dir have been ported. They
|
|
are tested on Win98, WinNT, Win2000 and WinXP.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="opensc.status.pkcs11">
|
|
<title>PKCS#11 Module in Netscape and Mozilla</title>
|
|
|
|
<para>
|
|
Netscape seems to show more information about
|
|
the security module than Mozilla. Otherwise all
|
|
stuff is untested.
|
|
</para>
|
|
|
|
<para>
|
|
Thread safety on Linux and Mac OS X:
|
|
Netscape/Mozilla uses the CKF_OS_LOCKING_OK
|
|
flag in C_Initialize(). The result is that the
|
|
browser process doesn't end when closing the
|
|
browser, so you have to kill the process
|
|
yourself. (If the browser would do a
|
|
C_Finalize, the sc_pkcs11_free_lock() would be
|
|
called and there wouldn't be a problem.)
|
|
</para>
|
|
|
|
<para>
|
|
Therefore, we don't use the PTHREAD locking
|
|
mechanisms, even if they are requested. This
|
|
seems to work fine for Mozilla, BUT will cause
|
|
problems for apps that use multiple threads to
|
|
access this lib simultaneously.
|
|
</para>
|
|
|
|
<para>
|
|
If you do want to use OS threading, compile
|
|
with -DPKCS11_THREAD_LOCKING On Windows, no
|
|
PTHREAD lib is used and there the problem
|
|
doesn't occur. So there the OS locking is
|
|
enabled.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.using">
|
|
<title>Using OpenSC</title>
|
|
|
|
<section id="opensc.using.netscape">
|
|
<title>OpenSC and Netscape</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
Select menu: Communicator -> Tools -> Security Info
|
|
</step>
|
|
|
|
<step>
|
|
Select Cryptographic Modules
|
|
</step>
|
|
|
|
<step>
|
|
Click: Add
|
|
</step>
|
|
|
|
<step>
|
|
Fill in module name: "OpenSC PKCS#11 Module"
|
|
and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so
|
|
</step>
|
|
</procedure>
|
|
|
|
<para>
|
|
For proper operation, you also need to configure the
|
|
module: In the Crypthographic Modules dialog, select
|
|
the OpenSC card, and click on the "Config" button to
|
|
the right. Select the "Enable this token" radio button,
|
|
and select the "Publicly readable Certs" button.
|
|
</para>
|
|
|
|
<para>
|
|
This will ensure that netscape uses the card when
|
|
trying to display encrypted messages in netscape
|
|
messenger. Setting "Publicly readable Certs" will also
|
|
stop a pretty annoying habit of netscape which is to
|
|
ask for all PINs when browsing sites requiring client
|
|
authentication.
|
|
</para>
|
|
|
|
<para>
|
|
You should _not_ select the "RSA" button. If this
|
|
option is selected, netscape will try to use the card
|
|
for all public key operations, and will fail horribly.
|
|
</para>
|
|
|
|
<para>
|
|
FIXME: this is for which versions of netscape?
|
|
</para>
|
|
</section>
|
|
|
|
<section id="opensc.using.mozilla">
|
|
<title>OpenSC and Mozilla</title>
|
|
|
|
<procedure>
|
|
<step>
|
|
Make sure Personal Security Manager (PSM) is
|
|
installed (eg. mozilla-psm package is
|
|
installed).
|
|
</step>
|
|
|
|
<step>
|
|
Select menu: Edit -> Preferences
|
|
</step>
|
|
|
|
<step>
|
|
Select category: Privacy & Security ->
|
|
Certificates
|
|
</step>
|
|
|
|
<step>
|
|
Click: Manage Security Devices
|
|
</step>
|
|
|
|
<step>
|
|
Click: Load
|
|
</step>
|
|
|
|
<step>
|
|
Fill in module name: "OpenSC PKCS#11 Module"
|
|
and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so
|
|
</step>
|
|
</procedure>
|
|
</section>
|
|
|
|
<section id="opensc.using.openssl">
|
|
<title>OpenSC and OpenSSL</title>
|
|
|
|
<para>
|
|
OpenSSL is a robust, full-featured toolkit
|
|
implementing the ssl protocols as well as
|
|
a general purpose cryptography library.
|
|
It features a so called engine interface
|
|
to combine the toolkit with the cryptographic
|
|
abilities of some hardware.
|
|
</para>
|
|
|
|
<para>
|
|
OpenSC includes an engine for OpenSSL. This
|
|
allowes to use the OpenSSL library and command line
|
|
utilities in combination with smart card cryptography.
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example how it works with the command
|
|
line tool <command>openssl</command>. You need
|
|
to load the opensc engine first, and then can
|
|
enter any command as usual (e.g. create or sign
|
|
a certificate).
|
|
</para>
|
|
|
|
<para>
|
|
Here is an example of how to load the engine.
|
|
<screen>
|
|
aj@simulacron:~$ openssl
|
|
OpenSSL> engine dynamic -pre SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so -pre ID:opensc -pre LIST_ADD:1 -pre LOAD
|
|
(dynamic) Dynamic engine loading support
|
|
[Success]: SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
|
|
[Success]: ID:opensc
|
|
[Success]: LIST_ADD:1
|
|
[Success]: LOAD
|
|
Loaded: (opensc) opensc engine
|
|
OpenSSL>
|
|
</screen>
|
|
</para>
|
|
|
|
<para>
|
|
A typical OpenSSL command might be to make a certificate request:
|
|
<prompt>req -engine opensc -new -key <replaceable>key</replaceable> -keyform engine -out req.pem -text</prompt>.
|
|
See the OpenSSL documentation for details.
|
|
</para>
|
|
|
|
<para>
|
|
- <replaceable>key</replaceable> can specify the ID of a key in hex,
|
|
- e.g. "45" would be key 0x45.
|
|
- </para>
|
|
|
|
<para>
|
|
Actualy Opensc has even two engines for Openssl:
|
|
<filename>engine_opensc.so</filename> and
|
|
<filename>engine_pkcs11.so</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
The opensc engine does only work with Opensc.
|
|
It will not work, if several applications
|
|
try to use the smart card at the same time
|
|
or one applications tries to use several
|
|
smart cards at the same time. Or several
|
|
certificates or keys within one card.
|
|
But for the simple case (one app, one cert, one
|
|
smart card) it is working very fine.
|
|
</para>
|
|
|
|
<para>
|
|
The pkcs11 engine is very generic and flexible.
|
|
It will always work, even in complex situations
|
|
involiving several cards, keys, objects, certificates
|
|
or concurrent applications. Also it is fully based
|
|
on pkcs11 and that way it can use the Opensc
|
|
pkcs11 library (and does so per default), but
|
|
it will work with any other pkcs11 library, too.
|
|
</para>
|
|
|
|
<para>
|
|
To load the pkcs11 engine issue this command:
|
|
<screen>
|
|
aj@simulacron:~$ openssl
|
|
OpenSSL> engine dynamic -pre SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/home/aj/opensc/lib/pkcs11/opensc-pkcs11.so
|
|
(dynamic) Dynamic engine loading support
|
|
[Success]: SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
|
|
[Success]: ID:pkcs11
|
|
[Success]: LIST_ADD:1
|
|
[Success]: LOAD
|
|
[Success]: MODULE_PATH:/home/aj/opensc/pkcs11/opensc-pkcs11.so
|
|
Loaded: (pkcs11) pkcs11 engine
|
|
OpenSSL>
|
|
</screen>
|
|
and then proceed as normal.
|
|
</para>
|
|
|
|
<para>
|
|
A typical OpenSSL command might be to make a certificate request:
|
|
<prompt>req -engine pkcs11 -new -key <replaceable>key</replaceable> -keyform engine -out req.pem -text</prompt>.
|
|
See the OpenSSL documentation for details.
|
|
</para>
|
|
|
|
<para>
|
|
<replaceable>key</replaceable> has the format <![CDATA[[slot_<slotNr>][-][id_<keyID>]]]>, in which
|
|
<itemizedlist>
|
|
<listitem>
|
|
the optional slotNr indicates which pkcs11 slot to take
|
|
(starting from 0, which is also the default)
|
|
</listitem>
|
|
<listitem>
|
|
keyID is the key ID in hex notation
|
|
</listitem>
|
|
</itemizedlist>
|
|
Examples:
|
|
<itemizedlist>
|
|
<listitem>
|
|
id_45 => private key with ID = 0x45 in the first 'suited' slot
|
|
</listitem>
|
|
<listitem>
|
|
slot_2-id_46 => private key with ID = 0x46 in the third slot
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
|
|
<para>
|
|
For Windows, only the pkcs11 engine (not the opensc engine) has been ported;
|
|
use "engine_pkcs11" instead of "engine_pkcs11.so".
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="opensc.using.openssh">
|
|
<title>OpenSC and OpenSSH</title>
|
|
|
|
<para>
|
|
Version 3.6.1p2 of OpenSSH needs a patch to
|
|
compile with OpenSC. You will find this patch
|
|
in src/openssh/.
|
|
</para>
|
|
|
|
<para>
|
|
When compiling OpenSSH you need to run configure like
|
|
this:
|
|
<prompt>./configure --with-opensc=/path/to/opensc</prompt>
|
|
</para>
|
|
|
|
<para>
|
|
You need to have a certificate on your smart card.
|
|
A key is not enough. Download the public key
|
|
of your certificate in Openssh format with
|
|
this command:
|
|
<prompt>ssh-keygen -D <replaceable>reader</replaceable><optional>:<replaceable>certificate ID</replaceable></optional> > <replaceable>file</replaceable></prompt>
|
|
</para>
|
|
|
|
<para>
|
|
Replace <replaceable>reader</replaceable> with the
|
|
number of the reader you want to use, default it 0.
|
|
<prompt>opensc-tool -l</prompt> will give you a list
|
|
of available readers. Add the certificate ID
|
|
if you need to select one. Default is 45.
|
|
<prompt>pkcs11-tool -O</prompt> will give you a list
|
|
of available certificates and their IDs.
|
|
</para>
|
|
|
|
<para>
|
|
Then transfer the public key to the desired server
|
|
and add it to <filename>~/.ssh/authorized_keys</filename> as usual.
|
|
</para>
|
|
|
|
<para>
|
|
To use a smart card with Openssh run
|
|
<prompt>ssh -I <replaceable>reader</replaceable><optional>:<replaceable>certificate ID</replaceable></optional></prompt>
|
|
</para>
|
|
|
|
<para>
|
|
You can also use the OpenSSH ssh-agent tool
|
|
with OpenSC. If you want to do so, use
|
|
<prompt>ssh-add -s <replaceable>reader</replaceable></prompt>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="opensc.using.pam">
|
|
<title>Pluggable Authentication Module</title>
|
|
|
|
<para>
|
|
Pluggable authantication modules or pam is
|
|
the default way under linux and other unix
|
|
operating systems to configure authentication.
|
|
OpenSC includes a module to allow smart card
|
|
based authentication: pam_opensc.
|
|
</para>
|
|
|
|
<para>
|
|
The following options are recognized:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>debug</term>
|
|
<listitem>log more debugging info</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>audit</term>
|
|
<listitem>a little more extreme than debug</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>use_first_pass</term>
|
|
<listitem>don't prompt the user for passwords, take them from PAM_ items insteat</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>try_first_pass</term>
|
|
<listitem>don't prompt the user for passwords unless PAM_(OLD)AUTHTOK in unsed</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>use_authtok</term>
|
|
<listitem>require PAM_AUTHTOK set, use it, fail otherwise</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>set_pass</term>
|
|
<listitem>set the PAM_ item swith the passwords used by this module</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>nodelay</term>
|
|
<listitem>used to prevent failed authentication resulting in a delay of about 1 second.</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>auth_method=X</term>
|
|
<listitem>choose either pkcs15-ldap or pkcs15-eid authentication. pkcs15-eid is the default.</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Generic options:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-h</term>
|
|
<listitem>Show help</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-r reader</term>
|
|
<listitem>Reader name (FIXME: not number?)</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<section id="opensc.using.pam.eid">
|
|
<title>eid based authentication</title>
|
|
|
|
<para>
|
|
This is the default authentication
|
|
method. Create a directory
|
|
<filename>.eid</filename> in your home
|
|
directory and copy your PEM encoded
|
|
certificat to the file
|
|
<filename>.eid/authorized_certificates</filename>.
|
|
</para>
|
|
|
|
<para>
|
|
Note: <prompt>pkcs15-tool -c</prompt>
|
|
will show you all certificates and
|
|
their ID, <prompt>pkcs15-tool -r ID -o
|
|
~/.eid/authorized_certificates</prompt>
|
|
will save the certificate
|
|
<replaceable>ID</replaceable> to that
|
|
file.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="opensc.using.pam.ldap">
|
|
<title>ldap based authentication</title>
|
|
|
|
<para>
|
|
Setting auth_method to pkcs15-ldap will
|
|
enable ldap based authenticaton.
|
|
These options are supported:
|
|
</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-L ldap.conf</term>
|
|
<listitem>Configuration file to load</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-A entry</term>
|
|
<listitem>Add new entry</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-E entry</term>
|
|
<listitem>Set current entry</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-H hostname</term>
|
|
<listitem>hostname of ldap server</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-P port</term>
|
|
<listitem>port or ldap server</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-S scope</term>
|
|
<listitem>scope of ldap server</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-b binddn</term>
|
|
<listitem>binddn for ldap connection</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-p passwd</term>
|
|
<listitem>password for ldap bind</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-B base</term>
|
|
<listitem>base for ldap bind</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-a attributes</term>
|
|
<listitem>attributes to fetch</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>-f filter</term>
|
|
<listitem>filter in ldap search</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
<para>
|
|
FIXME: provide an example
|
|
of ldap data structure, config
|
|
file etc.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.pkcs11">
|
|
<title>The OpenSC PKCS11 library</title>
|
|
|
|
<section id="opensc.pkcs11.whatis">
|
|
<title>What is PKCS11</title>
|
|
|
|
<para>
|
|
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(), ...
|
|
</para>
|
|
|
|
<para>
|
|
Some core concepts of pkcs11 are:
|
|
<itemizedlist>
|
|
<listitem>
|
|
slot: the place in which a smart card can be put. Usually this
|
|
corresponds with a card reader (but: see below, Virtual slots).
|
|
</listitem>
|
|
<listitem>
|
|
token: the thing that is put in a slot. Usually this corresponds
|
|
with a smart card (but: see below, virtual slots).
|
|
</listitem>
|
|
<listitem>
|
|
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).
|
|
</listitem>
|
|
<listitem>
|
|
session: before you can do anything with a token, you have to
|
|
open a session on it.
|
|
</listitem>
|
|
<listitem>
|
|
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
|
|
on the same token.
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="opensc.pkcs11.slots">
|
|
<title>Virtual slots</title>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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:
|
|
<itemizedlist>
|
|
<listitem>
|
|
token in slot 4: PIN 1, key 1, cert chain 1
|
|
</listitem>
|
|
<listitem>
|
|
token in slot 5: PIN 2, key 2, cert chain 2
|
|
</listitem>
|
|
<listitem>
|
|
token in slot 6: the 3 other root certs
|
|
</listitem>
|
|
<listitem>
|
|
token in slot 7: no data
|
|
</listitem>
|
|
</itemizedlist>
|
|
If hide_empty_tokens would have been true, slot 7 wouldn't show
|
|
a token.
|
|
</para>
|
|
|
|
<para>
|
|
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).
|
|
</para>
|
|
|
|
<para>
|
|
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.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.todo">
|
|
<title>What needs to be done</title>
|
|
|
|
<screen>
|
|
* Debian packaging
|
|
* GUI applications
|
|
* Ports to MacOS X (jey) and Win32 (fabled?)
|
|
* Add support for EMV and GSM (anyone?)
|
|
</screen>
|
|
|
|
<screen>
|
|
* Pin pad support
|
|
* Merge DODF patches (mostly done)
|
|
* put generic PEM encoding/decoding functions into libopensc?
|
|
* Merge pkcs11 proxy from Zetes
|
|
* pkcs11: support decrypt for those cards that have it
|
|
* pkcs11: make sure all PIN ops work through pkcs11
|
|
* pkcs11: unblock pins: check for unblock pins in AODF
|
|
* all: support for RSA-PSS
|
|
* pkcs15-init: support SOPIN on Cryptoflex
|
|
* pkcs15-init: use max. possible usage by default
|
|
* pkcs15-init: during keygen, make sure the pubkey usage is right
|
|
* pkcs15-init: when using an unblock PIN, write an AODF entry for it
|
|
(alternatively: set unblockDisabled flag for those PINs that have no PUK?)
|
|
* pkcs15: fix sc_pkcs15_change_reference_data; add unblock function
|
|
* pkcs11: make sure all PIN ops work through pkcs11
|
|
</screen>
|
|
|
|
<section id="opensc.todo.windows">
|
|
<title>Windows</title>
|
|
|
|
<para>
|
|
Other parts of OpenSC be should ported as well.
|
|
Also we should implement native Win32 APIs such
|
|
as CryptoAPI Provider, some login stuff and
|
|
ActiveX plugin for Explorer to do the signing.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
|
|
<chapter id="opensc.help">
|
|
<title>Troubleshooting</title>
|
|
|
|
<para>
|
|
A mailing-list has been set up for support and
|
|
discussion about the OpenSC project. Additional info is
|
|
available at OpenSC web site.
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.links">
|
|
<title>Resources</title>
|
|
|
|
<para>
|
|
See the OpenSC web site at
|
|
<ulink url="http://www.opensc.org/" />
|
|
</para>
|
|
|
|
<para>
|
|
Information about Assuan and project Ägypten:
|
|
<ulink url="http://www.gnupg.org/aegypten/" />
|
|
</para>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.signer">
|
|
<title>Signer</title>
|
|
|
|
<para>
|
|
OpenSC Signer is a Netscape plugin that will generate
|
|
digital signatures using facilities on PKI-capable
|
|
smartcards.
|
|
</para>
|
|
|
|
<section id="opensc.signer.install">
|
|
<title>Building and Installing libopensc</title>
|
|
|
|
<para>
|
|
You should specify your plugin directory with:
|
|
<prompt> $ configure --with-plugin-dir=<replaceable><directory></replaceable></prompt>
|
|
</para>
|
|
|
|
<para>
|
|
Common plugin directories are
|
|
/usr/lib/mozilla/plugins and
|
|
/usr/lib/netscape/plugins.
|
|
</para>
|
|
|
|
<para>
|
|
See the INSTALL file for more instructions.
|
|
</para>
|
|
|
|
<para>
|
|
NOTE: PIN code dialog is done through libassuan
|
|
from Project Ägypten. If you don't have it
|
|
installed already, download it from the link
|
|
below.
|
|
</para>
|
|
</section>
|
|
</chapter>
|
|
|
|
<chapter id="opensc.docbook">
|
|
<title>A few hints on docbook documents</title>
|
|
|
|
<para>
|
|
This document is maintained as docbook xml
|
|
document. Here are some hints and links for
|
|
newcomers.
|
|
</para>
|
|
|
|
<para>
|
|
This document is written in XML not SGML.
|
|
To convert it, use a XSL stylesheet, not
|
|
an DSSSL stylesheet. Ignore all tools and
|
|
webpages talking about SGML or DSSSL, those
|
|
talk about legecy technology no longer used
|
|
and no longer up to date.
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://docbook.sf.net/">The Docbook
|
|
Project</ulink> at Sourceforge has the
|
|
XSL stylshet used to convert this XML document
|
|
to other formats.
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.docbook.org/">Docbook, the
|
|
definite Guide (O'Reilly Book)</ulink> documents
|
|
Docbook, is very handy as reference and available
|
|
Online for free.
|
|
</para>
|
|
|
|
<para>
|
|
<ulink url="http://www.sagehill.net/docbookxsl/">Online
|
|
Book on Docbook, XML and XSL</ulink> is a book
|
|
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.
|
|
</para>
|
|
|
|
<para>
|
|
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 <ulink url="http://docbook.sourceforge.net/release/xsl/current/doc/html/">Reference for the HTML stylesheet parameters</ulink>), but most stuff can be improved via CSS
|
|
styles. We need help on this !
|
|
</para>
|
|
</chapter>
|
|
</book>
|