root/releases/opensc-0.9.4/QUICKSTART

A quick installation guide to opensc
====================================

To install opensc, please do as user,

$ wget http://www.opensc.org/files/opensc-0.9.4.tar.gz
$ tar xfvz opensc-0.9.4.tar.gz
$ cd opensc-0.9.4

nothing special so far.

$ ./configure --prefix=/usr --sysconfdir=/etc

This will install opensc in /usr with the config file in /etc.
If you installed openct at some special place opensc might not
find it. Please add "--with-openct=/path/to/openct" to make
sure it is found. At the end of the configure script, opensc
will print a summary page, too. It should look like this:

OpenSC has been configured with the following options

User binaries:       /usr/bin
Configuration files: /etc

Host:                i686-pc-linux-gnu
Compiler:            gcc
Compiler flags:      -Wall -fno-strict-aliasing -g -O2 
Preprocessor flags:  -I${top_builddir}/src/include 
Linker flags:        -L/usr -L/usr/lib -L/usr/lib 
Libraries:           -lpthread 

Random number collection: device (/dev/urandom)
OpenSSL support:          yes
        with engine:      yes
PC/SC support:            yes
OpenCT support:           yes
Assuan support:           no
LDAP support:             yes
PAM support:              yes


OpenSSL support is very important, some cards cannot work without.
I strongly suggest to use a recent version. Best is 0.9.7d or later,
as the OpenSSL project improved one issue very important to opensc.
But older versions will work fine, too.

If you want to use openssl version 0.9.6, be aware that it is available in two
flavors: the normal version and an "engine" version. Only with the "engine"
version OpenSC can provide full OpenSSL support, including two engines for
OpenSSL.

With OpenSSL 0.9.7 you don't need to worry, the engine support is always
enabled.

OpenSC is about smart cards. You need some software that knows smart
card readers to access the cards in them. OpenSC supports three flavors:
 - CT-API is a very simple interface, and there are many drivers for it,
   mostly binary only. This support is always build into OpenSC.
   But it is recommended to use this only for testing, or in environments
   with a single user and a single application using smart cards.
 - PC/SC is a standard used in the Windows world. But the pcsc-lite software
   implements this standard for Unix and Mac OS X, too, and many drivers
   are available for it. Some are open source, many are binary only.
 - OpenCT is an open source software implementing smart card drivers for
   many smart card readers and usb tokens. OpenCT does not follow any
   standard, but instead it is small, lean, and still has everything
   needed to do the job. OpenCT is only available on Linux and Unix-like
   operating systems, but not on Windows.

If OpenCT supports your reader, it is the recommended choice to use.
Otherwise if there is a driver for pcsc-lite, that is your best alternative.

Note: it is possible to use OpenCT both directly with OpenSC,
but you can also create a chain OpenCT -> PC/SC-Lite -> OpenSC.
Such a chain is only recommended, if applications other than OpenSC
need to access the same readers and smart cards, too. Otherwise
it adds an overhead and is not tested very much.

Note also that OpenSC can use both, OpenCT and PC/SC-Lite at the
same time. So if both are turned on, that is fine.

To use OpenSC with GnuPG, first compile the assuan library, then compile
OpenSC with support for Assuan, and then compile GnuPG with OpenSC. This
only works with development versions of GnuPG (1.9.*) and has not been
well tested. Feedback is very welcome. Other than to use OpenSC with
GnuPG, the Assuan support is not needed.

PAM support allowes you to use a smart card and the opensc PAM module
to log into your system. If enabled, the pam module has two flavors:
it can compare a key on a smart card to a certificate stored localy,
or it can communicate with an LDAP server to check the key and
certificate stored on a smart card. The former mode requires only
PAM support, the later is only available, if OpenSC is compiled with
LDAP and PAM support enabled.

Now if your configuration is similar, you can compile the software.

$ make
$ su root

and install the software as root
# make install

usualy opensc is fine without any config file, still you can install it:

# cp etc/opensc.conf.example /etc/opensc.conf
# cp etc/scldap.conf.example /etc/scladp.conf

If you have some reason to edit the config file, feel free to do so.
But most users are fine without.

OpenSC is now fully installed. Have fun.

Some usual commands include:

$ 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)

You can see, openct claims five slots, but only two are used.
This is done to support hotplugging. If you are using OpenCT
and PC/SC-Lite, please use this test often to make sure you
are using some openct driver directly, and not indirectly
via openct. In theory both should work fine, but if you have
some problems, please test this.

$ opensc-tool --reader 1 --atr
3B E2 00 FF C1 10 31 FE 55 C8 02 9C ;.....1.U...

OpenCT can give you the atr as well.

$ opensc-explorer

Is a tool to explore the smart card - list directories, change
directories, look at files, and so on. If this doesn't work,
do not panic. Many cards simply do not support this, they
have no "ls" command. Many other tools will still work.


Quick start guide to initializing a card
========================================

If opensc and openct are both installed and can see the reader
and the card, you might want to start formatting it, creating
an pkcs#15 structure, adding a user name and pin, generate a key,
create a certificate and use it everywhere. Here is the quick guide.

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.

$ 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: 

This created an empty pkcs15 structure. You can't do much without it.
Also I entered a pin for the security officer, and an unblocking pin.
As a general rule, the SO pin is required everytime you change the
card, but only the user pin is required to use it.

$ 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: 

I created a user with my name on it, so it is easier to see who uses
this card. The security officer pin is required as this changes the
card. However later to use it, the security officer pin will never
work, there is no way for the security officer to get to my key.
Also I need to remember my unblocking pin, as only I can reset it,
the security officer cannot.

$ 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: 

This created an RSA key that I as User can use.
Lets create a new self-signed certificate with it.
To do this, we use openssl.

$ openssl
OpenSSL> engine dynamic -pre SO_PATH:/usr/lib/opensc/engine_pkcs11.so \
        -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD
(dynamic) Dynamic engine loading support
[Success]: SO_PATH:/home/aj/opentest/lib/opensc/engine_pkcs11.so
[Success]: ID:pkcs11
[Success]: LIST_ADD:1
[Success]: LOAD
Loaded: (pkcs11) pkcs11 engine
OpenSSL>

It is important to enter the whole long command in one single command
line. I usualy copy&paste the command, to make sure I don't mistype
anything. This command loads the opensc engine, so openssl can delegate
some work from your computers cpu to the smart card.

OpenSSL> req -engine pkcs11 -new -key id_45 -keyform engine -out req.pem -text -x509
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> 

So now I have a signed certificate. Remove the final "-x509" if you want
a certificate signing request only. In that case, send the request
to the CA, wait till you get it back, signed, and proceed as normal.

Now store the certificate side by side with the key. It is important
to save the certificate under the same ID as the key. You can get
a list of all keys and their details (including the ID) with:

$ 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

So lets store the key:
$ pkcs15-init --store-certificate req.pem --auth-id 01 --id 45 --format pem 
Security officer PIN required.
Please enter Security officer PIN: 

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.