Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

file 266 lines (214 sloc) 10.349 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266
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 /etc/opensc.conf
# cp etc/scldap.conf /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.
Something went wrong with that request. Please try again.