From 46021acdaac43ca5b4512d910f13c3dad24fd16d Mon Sep 17 00:00:00 2001 From: aj Date: Thu, 20 Oct 2005 12:55:17 +0000 Subject: [PATCH] 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 --- Makefile.am | 2 +- QUICKSTART | 267 ---------------------------------------------------- README | 32 +++++++ 3 files changed, 33 insertions(+), 268 deletions(-) delete mode 100644 QUICKSTART create mode 100644 README diff --git a/Makefile.am b/Makefile.am index 38779b18..c1b84a85 100644 --- a/Makefile.am +++ b/Makefile.am @@ -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 diff --git a/QUICKSTART b/QUICKSTART deleted file mode 100644 index d75bf2b1..00000000 --- a/QUICKSTART +++ /dev/null @@ -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. - diff --git a/README b/README new file mode 100644 index 00000000..f6aebe99 --- /dev/null +++ b/README @@ -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.