268 lines
10 KiB
Plaintext
268 lines
10 KiB
Plaintext
A quick installation guide to opensc
|
|
====================================
|
|
|
|
To install opensc, please do as user,
|
|
|
|
$ wget http://www.opensc.org/files/opensc-x.y.z.tar.gz
|
|
$ tar xfvz opensc-x.y.z.tar.gz
|
|
$ cd opensc-x.y.z
|
|
|
|
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 locally,
|
|
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
|
|
|
|
usually 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/scldap.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
|
|
|
|
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 every time 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 usually 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.
|
|
|