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:
aj
parent
e0465478e7
commit
46021acdaa
|
|
@ -3,7 +3,7 @@
|
|||
SUBDIRS = . aclocal etc man src win32
|
||||
DIST_SUBDIRS = . aclocal doc etc man src win32
|
||||
|
||||
EXTRA_DIST = CodingStyle QUICKSTART \
|
||||
EXTRA_DIST = CodingStyle README \
|
||||
bootstrap Makefile.mak depcomp \
|
||||
solaris/Makefile solaris/README solaris/checkinstall.in \
|
||||
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