remove QUICKSTART (outdated and replaced by wiki documentation "QuickStart")
and add README pointing people to our wiki / html documentation. git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@2651 c6295689-39f2-0310-b995-f0e70906c6a9
This commit is contained in:
parent
e0465478e7
commit
46021acdaa
|
@ -3,7 +3,7 @@
|
||||||
SUBDIRS = . aclocal etc man src win32
|
SUBDIRS = . aclocal etc man src win32
|
||||||
DIST_SUBDIRS = . aclocal doc etc man src win32
|
DIST_SUBDIRS = . aclocal doc etc man src win32
|
||||||
|
|
||||||
EXTRA_DIST = CodingStyle QUICKSTART \
|
EXTRA_DIST = CodingStyle README \
|
||||||
bootstrap Makefile.mak depcomp \
|
bootstrap Makefile.mak depcomp \
|
||||||
solaris/Makefile solaris/README solaris/checkinstall.in \
|
solaris/Makefile solaris/README solaris/checkinstall.in \
|
||||||
solaris/opensc.conf-dist solaris/pkginfo.in solaris/proto
|
solaris/opensc.conf-dist solaris/pkginfo.in solaris/proto
|
||||||
|
|
267
QUICKSTART
267
QUICKSTART
|
@ -1,267 +0,0 @@
|
||||||
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 --key-usage sign,decrypt
|
|
||||||
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
|
|
||||||
Smart card 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.
|
|
||||||
|
|
|
@ -0,0 +1,32 @@
|
||||||
|
OpenSC documentation is now maintained in our online wiki at
|
||||||
|
http://www.opensc.org/opensc/
|
||||||
|
and a copy in html format is provided in the doc/ directory
|
||||||
|
with all releases or snapshots of OpenSC in tar.gz files.
|
||||||
|
|
||||||
|
Please take a look at the documentation before trying to
|
||||||
|
install OpenSC. Most important are the pages
|
||||||
|
|
||||||
|
OverView
|
||||||
|
A short introduction what OpenSC is and how it fits into the big picture.
|
||||||
|
|
||||||
|
WhatsNew
|
||||||
|
What is new, what has changed since the last major release?
|
||||||
|
|
||||||
|
OperatingSystems
|
||||||
|
What your operating system needs to have for OpenSC to work.
|
||||||
|
|
||||||
|
CompilingInstalling
|
||||||
|
How to compile and install OpenSC yourself.
|
||||||
|
|
||||||
|
QuickStart
|
||||||
|
installation and basic steps to initialize a blank smart card.
|
||||||
|
|
||||||
|
UsingOpensc
|
||||||
|
options when using OpenSC.
|
||||||
|
|
||||||
|
|
||||||
|
Also check the specific pages of the smart cards or crypto tokens you want
|
||||||
|
to use. If you have any trouble the MailingLists page will tell you how
|
||||||
|
to contact us for help.
|
||||||
|
|
||||||
|
Regards, the OpenSC Team.
|
Loading…
Reference in New Issue