From 3f7599caaa691037f2df94072de2128af176548a Mon Sep 17 00:00:00 2001 From: aj Date: Wed, 27 Aug 2003 08:47:09 +0000 Subject: [PATCH] =?UTF-8?q?Documentation=20fixes=20by=20Ville=20Skytt?= =?UTF-8?q?=EF=BF=BD=EF=BF=BD.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@1394 c6295689-39f2-0310-b995-f0e70906c6a9 --- docs/opensc.html | 3159 +++++++++++++++++++++++++++++++--------------- docs/opensc.xml | 232 ++-- 2 files changed, 2286 insertions(+), 1105 deletions(-) diff --git a/docs/opensc.html b/docs/opensc.html index 5e547c84..9ba8ff05 100644 --- a/docs/opensc.html +++ b/docs/opensc.html @@ -1,1626 +1,2795 @@ - + + - - OpenSC Manual - - + + + + OpenSC Manual + + + + + + +

- OpenSC Manual

+ OpenSC Manual +
+

+
-
+ +
+

- Table of Contents + + Table of Contents +

+
-
1. - Introduction
-
2. - Authors and - Contributors
+
+ 1. + + + Introduction + +
+ +
+ 2. + + + Authors and Contributors + +
+
- Thanks + + Thanks +
-
3. - Copyright and License
-
4. - Overview
+ +
+ 3. + + + Copyright and License + +
+ +
+ 4. + + + Overview + +
+
- Layers in - libopensc + + Layers in libopensc +
+
- The reader - layer + + The reader layer +
-
5. - Building and Installing - libopensc
+ +
+ 5. + + + Building and Installing libopensc + +
+
- Windows + + Windows +
+
- Windows - with OpenSSL + + Windows with OpenSSL +
-
6. - Status
+ +
+ 6. + + + Status + +
+
- Card Status + + Card Status +
+
- Windows + + Windows +
+
- PKCS#11 Module in - Netscape and Mozilla + + PKCS #11 Module in Netscape and Mozilla +
-
7. - Using OpenSC
+ +
+ 7. + + + Using OpenSC + +
+
- OpenSC and - Netscape + + OpenSC and Netscape +
+
- OpenSC and - Mozilla + + OpenSC and Mozilla +
+
- OpenSC and - OpenSSL + + OpenSC and OpenSSL +
+
- OpenSC and - OpenSSH + + OpenSC and OpenSSH +
+
- Pluggable - Authentication Module + + Pluggable Authentication Module +
+
- eid based - authentication + + eid based authentication +
+
- ldap based - authentication + + LDAP based authentication +
-
8. - The OpenSC PKCS11 - library
+ +
+ 8. + + + The OpenSC PKCS #11 library + +
+
- What is PKCS11 + + What is PKCS #11 +
+
- Virtual slots + + Virtual slots +
-
9. - What needs to be done
+ +
+ 9. + + + What needs to be done + +
+
- Windows + + Windows +
-
10. - Troubleshooting
-
11. - Resources
-
12. - Signer
+ +
+ 10. + + + Troubleshooting + +
+ +
+ 11. + + + Resources + +
+ +
+ 12. + + + Signer + +
+
- Building and - Installing libopensc + + Building and installing the OpenSC Signer +
-
13. - A few hints on docbook - documents
+ +
+ 13. + + + A few hints on DocBook documents + +
+

- - Chapter 1. Introduction

+ + Chapter 1. Introduction +
+
-

libopensc is a library for accessing SmartCard devices - using PC/SC Lite middleware package. It is also the core - library of the OpenSC project. Basic functionality (e.g. - SELECT FILE, READ BINARY) should work on any ISO 7816-4 - compatible SmartCard. Encryption and decryption using - private keys on the SmartCard is at the moment possible - only with PKCS#15 compatible cards, such as the FINEID - (Finnish Electronic IDentity) card manufactured by - Setec.

+ +

+ libopensc is a library for accessing smart card devices + using PC/SC Lite middleware package. It is also the core + library of the OpenSC project. Basic functionality (e.g. + SELECT FILE, READ BINARY) should work on any ISO 7816-4 + compatible smart card. Encryption and decryption using + private keys on the smart card is at the moment possible + only with PKCS #15 compatible cards, such as the FINEID + (Finnish electronic ID card) card manufactured by Setec. +

+

- - Chapter 2. Authors and - Contributors

+ + Chapter 2. Authors and Contributors +
+
+

- Table of Contents + + Table of Contents +

+
- Thanks + + Thanks +
-

Here is a list of all Authors and Contributors of OpenSC - in alphabetical order:

+ +

+ Here is a list of all Authors and Contributors of OpenSC + in alphabetical order: +

+
+

- Thanks

+ Thanks +
+
-

The following people provided inspiration, moral - support and/or valuable information during the - development of OpenSC:

+ +

+ The following people provided inspiration, moral + support and/or valuable information during the + development of OpenSC: +

+
-

OpenSC did neither invent the wheel nor write all code - from scratch. We could reuse some code from other - projects mostly to interface with these projects. Thanks - to the original authors:

+ +

+ OpenSC did neither invent the wheel nor write all code + from scratch. We could reuse some code from other + projects mostly to interface with these projects. + Thanks to the original authors: +

+
+

- - Chapter 3. Copyright and License

+ + Chapter 3. Copyright and License +
+
+ 
-OpenSC smart card library
-Copyright (C) OpenSC developers 
+                OpenSC smart card library
+                Copyright (C) OpenSC developers 
 
-This library is free software; you can redistribute it and/or
-modify it under the terms of the GNU Lesser General Public
-License as published by the Free Software Foundation; either
-version 2.1 of the License, or (at your option) any later version.
+                This library is free software; you can redistribute
+                it and/or
+                modify it under the terms of the GNU Lesser General
+                Public
+                License as published by the Free Software
+                Foundation; either
+                version 2.1 of the License, or (at your option) any
+                later version.
 
-This library is distributed in the hope that it will be useful,
-but WITHOUT ANY WARRANTY; without even the implied warranty of
-MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
-Lesser General Public License for more details.
+                This library is distributed in the hope that it
+                will be useful,
+                but WITHOUT ANY WARRANTY; without even the implied
+                warranty of
+                MERCHANTABILITY or FITNESS FOR A PARTICULAR
+                PURPOSE.  See the GNU
+                Lesser General Public License for more details.
 
-You should have received a copy of the GNU Lesser General Public
-License along with this library; if not, write to the Free Software
-Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 
-02111-1307  USA
-
+ You should have received a copy of the GNU Lesser + General Public + License along with this library; if not, write to + the Free Software + Foundation, Inc., 59 Temple Place, Suite 330, + Boston, MA 02111-1307 USA +
+

- - Chapter 4. Overview

+ + Chapter 4. Overview +
+
+

- Table of Contents + + Table of Contents +

+
- Layers in - libopensc + + Layers in libopensc +
+
- The reader - layer + + The reader layer +
-

OpenSC is a large toolkit. The main building block is - the opensc library. It has three layers of code, each with - several drivers in it. Other libraries are the pkcs11 - module, a pam module, two engines for openssl. In addition - there are several tools to test and use these tools and - libraries.

-

Purpose of this chapter is to give an overview of the - inner workings of the opensc library, to give a short - presentation what the other libraries do, and finaly what - the opensc toolchest has to offer. Each tool has it's own - man page, each library it's own section in this - document.

+ +

+ OpenSC is a large toolkit. The main building block is the + opensc library. It has three layers of code, each with + several drivers in it. Other libraries are the PKCS #11 + module, a PAM module, two engines for OpenSSL. In + addition there are several tools to test and use these + tools and libraries. +

+ +

+ Purpose of this chapter is to give an overview of the + inner workings of the opensc library, to give a short + presentation what the other libraries do, and finally + what the opensc toolchest has to offer. Each tool has + it's own man page, each library it's own section in this + document. +

+

- Layers in - libopensc

+ Layers in + libopensc +
+
-

libopensc is the basic library used by everthing else. - It offer basic functionality like talking to smart cards, - but also advances functions like generating rsa keys on a - smart card.

-

libopensc has several layers of functionality, each - implemented by one or several drivers. The layers - are:

+ +

+ libopensc is the basic library used by everything else. + It offer basic functionality like talking to smart + cards, but also advances functions like generating RSA + keys on a smart card. +

+ +

+ libopensc has several layers of functionality, each + implemented by one or several drivers. The layers are: +

+
- reader -
-
OpenSC needs some way to talk to smart card - readers and cards in the smart card readers. - Different software can be used for that purpose, each - software has it's own reader module so OpenSC can use - that software.
-
- card -
-
In a perfect world all smart cards would - implement ISO 7816 standard, and thus accept the same - commands and give the same answers. Unfortunatly most - cards have their own commands, syntax and responses. - The card modules in libopensc implement these - different commands.
-
- pkcs15init -
-
Smart cards usualy have a file system. To store - or create keys or certiticates on a smart card one - needs to format the card, create directories and - objects and set permissions in a secure way. Not only - are the commands to do this different from card to - card, also the security model is often very - different. These pkcs15init modules implement these - differences.
-
- pkcs15 framework + + reader +
+
-

PKCS#15 is the standard on how to store - certificates and keys on a smart card or crypto - token. But many vendors have their own proprietory - mechanism for storing these informations, for - example in different directories. OpenSC implements - the PKCS#15 standard, but there is also an - emulation module for a slightly incompatible - storage mechanism in the works.

-

It should be possible to implement a completely - differennt framework for compatiblity with a non - pkcs#15 way of storing and accessing keys and - certificates.

+ OpenSC needs some way to talk to smart card readers + and cards in the smart card readers. Different + software can be used for that purpose, each + software has it's own reader module so OpenSC can + use that software. +
+ +
+ + card + +
+ +
+ In a perfect world all smart cards would implement + ISO 7816 standard, and thus accept the same + commands and give the same answers. Unfortunately + most cards have their own commands, syntax and + responses. The card modules in libopensc implement + these different commands. +
+ +
+ + pkcs15init + +
+ +
+ Smart cards usually have a file system. To store or + create keys or certificates on a smart card one + needs to format the card, create directories and + objects and set permissions in a secure way. Not + only are the commands to do this different from + card to card, also the security model is often very + different. These pkcs15init modules implement these + differences. +
+ +
+ + PKCS #15 framework + +
+ +
+

+ + PKCS #15 + is the standard on how to store certificates + and keys on a smart card or crypto token. But + many vendors have their own proprietary mechanism + for storing these informations, for example in + different directories. OpenSC implements the PKCS + #15 standard, but there is also an emulation + module for a slightly incompatible storage + mechanism in the works. +

+ +

+ It should be possible to implement a completely + different framework for compatibility with a non + PKCS #15 way of storing and accessing keys and + certificates. +

+

- The reader - layer

+ The reader + layer +
+
-

PC/SC-Lite is well known as smart card middleware. It - interacts with drivers for the smart card readers on the - buttom, and with smart card applications on the top. - OpenSC can use PC/SC-Lite via the pcsc reader module, but - also supports a number of alternatives.

-

PC/SC is a standard with interfaces betweens - applications, a resource manager and drivers for smart - card readers. This standard is very popular on the - Windows operating System. The documents are available - from the - - http://www.pcscworkgroup.com/.

-

PC/SC-Lite is an implementation of the PC/SC standard - for linux, Unix, Mac OS X and Windows by David Corcoran - . The software is - available with full source code and available for free. - To download the software, please visit the website of the - Movement for the use of smart cards in a linux - environment (M.U.S.C.L.E.) at - - http://www.linuxnet.com/.

-

To install OpenSC with support for PC/SC-Lite, please - install PC/SC-Lite first. Then configure OpenSC to use - PC/SC-Lite and specify the location where PC/SC-Lite is - installed like this:

+ +

+ PC/SC Lite is well known as smart card middleware. It + interacts with drivers for the smart card readers on + the bottom, and with smart card applications on the + top. OpenSC can use PC/SC Lite via the pcsc reader + module, but also supports a number of alternatives. +

+ +

+ PC/SC is a standard with interfaces between + applications, a resource manager and drivers for smart + card readers. This standard is very popular on the + Windows operating System. The documents are available + from + + + http://www.pcscworkgroup.com/ + . +

+ +

+ PC/SC Lite is an implementation of the PC/SC standard + for Linux, Unix, Mac OS X and Windows by David Corcoran + + + . The software is available with full source code + and available for free. To download the software, + please visit the website of the Movement for the use of + smart cards in a Linux environment (M.U.S.C.L.E.) at + + + http://www.linuxnet.com/ + . +

+ +

+ To install OpenSC with support for PC/SC Lite, please + install PC/SC Lite first. Then configure OpenSC to use + PC/SC Lite and specify the location where PC/SC Lite is + installed like this: +

+ 
-$ cd opensc-0.8.0
-$ ./configure --with-pcsclite=/path/to/pcsclite
-
+ $ cd opensc-0.8.0 + $ ./configure --with-pcsclite=/path/to/pcsclite + +
+

-

OpenCT is a new framework for accessing smart cards, - card readers and card terminals. It was written from - scratch, already includes all drivers, and is very - lightwight. OpenCT is available for linux, but if you - want to use it on other Unix or BSD operating systems, - please ask for help on the opensc-devel mailing list.

-

OpenCT is open source software. As such it is availble - with full source code for free. OpenCT is a software - companion to OpenSC and the prefered way of accessing - smart cards under linux. OpenCT is available from the - OpenSC website - - http://www.opensc.org/and questions go to the - mailing list.

-

To compile OpenSC with support for OpenCT, please - install OpenCT first. Documentation on OpenCT is part of - the source code, and also available online at - - http://www.opensc.org/files/doc/openct.html. Then - configure OpenSC to use OpenCT and specify the location - where OpenCT is installed like this:

-

Usbtoken is a small driver for usb crypto devices - only. It does not need any other helper software and is - included in OpenSC for convinience. However Usbtoken is - deprecated, the new OpenCT software is now the - recommended way to access usb crypto tokens. Usbtoken is - no longer activly developed, but bugs are still fixed and - help is provided on the OpenSC mailing list at - .

-

If you still want to use OpenSC with Usbtoken, please - configure OpenSC like this:

+ +

+ OpenCT is a new framework for accessing smart cards, + card readers and card terminals. It was written from + scratch, already includes all drivers, and is very + lightweight. OpenCT is available for Linux, but if you + want to use it on other Unix or BSD operating systems, + please ask for help on the opensc-devel mailing list. +

+ +

+ OpenCT is open source software. As such it is available + with full source code for free. OpenCT is a software + companion to OpenSC and the preferred way of accessing + smart cards under Linux. OpenCT is available from the + OpenSC website + + + http://www.opensc.org/ + and questions go to the + + mailing list. +

+ +

+ To compile OpenSC with support for OpenCT, please + install OpenCT first. Documentation on OpenCT is part + of the source code, and also available online at + + + http://www.opensc.org/files/doc/openct.html + . Then configure OpenSC to use OpenCT and specify + the location where OpenCT is installed like this: +

+ 
-$ cd opensc-0.8.0
-$ ./configure --enable-usbtoken
-
+ $ cd opensc-0.8.0 + $ ./configure --with-openct=/path/to/openct + +
+

-

Documentation on Usbtoken is in the file - - usbtoken.html.

-

CT-API is a standard format for drivers for smart card - readers. It was invented in the eighties for DOS - applications and is maybe not very fit for todays - multiuser multitasking applications. However CT-API is - still quite popular, and many smart card readers have - drivers in CT-API format even for linux. It is - recommended to use these drivers if the PC/SC-Lite - middleware described above.

-

But OpenSC can also use CT-API drivers directly. This - is meant for debugging mostly and not recommended in a - multi user or multi application environment.

-

OpenSC includes always support for drivers in CT-API - format, you don't need to do anything special for - compiling. See the - opensc.confconfiguration file - on how to configure an CT-API driver with OpenSC.

+ +

+ Usbtoken is a small driver for usb crypto devices only. + It does not need any other helper software and is + included in OpenSC for convenience. However Usbtoken is + deprecated, the new OpenCT software is now the + recommended way to access usb crypto tokens. Usbtoken + is no longer actively developed, but bugs are still + fixed and help is provided on the OpenSC mailing list + at + + . +

+ +

+ If you still want to use OpenSC with Usbtoken, please + configure OpenSC like this: +

+ + + + + +
+ 
+                  $ cd opensc-0.8.0
+                  $ ./configure --enable-usbtoken
+                                                  
+
+
+ +

+ +

+ Documentation on Usbtoken is in the file + + + usbtoken.html + . +

+ +

+ CT-API is a standard format for drivers for smart card + readers. It was invented in the eighties for DOS + applications and is maybe not very fit for todays + multiuser multitasking applications. However CT-API is + still quite popular, and many smart card readers have + drivers in CT-API format even for Linux. It is + recommended to use these drivers if the PC/SC Lite + middleware described above. +

+ +

+ But OpenSC can also use CT-API drivers directly. This + is meant for debugging mostly and not recommended in a + multi user or multi application environment. +

+ +

+ OpenSC includes always support for drivers in CT-API + format, you don't need to do anything special for + compiling. See the + + + opensc.conf + configuration file on how to configure an CT-API + driver with OpenSC. +

+

- - Chapter 5. Building and Installing - libopensc

+ + Chapter 5. Building and Installing + libopensc +
+
+

- Table of Contents + + Table of Contents +

+
- Windows + + Windows +
+
- Windows with - OpenSSL + + Windows with OpenSSL +
-

See the INSTALL file for instructions. If you are using - the CVS version, you have to run the 'bootstrap' script - before running configure. Please note, that for bootstrap - to work, you have to have the correct versions of Autoconf, - Automake and Libtool installed.

+ +

+ See the INSTALL file for instructions. If you are using + the CVS version, you have to run the 'bootstrap' script + before running configure. Please note, that for bootstrap + to work, you have to have the correct versions of + Autoconf, Automake and Libtool installed. +

+

- Windows

+ Windows +
+
-

Type "nmake -f makefile.mak" in the opensc\ dir to - compile.

-

You need also perl and flex installed for the compile - process to complete succesfully.

-

No installation script has been provided, so you have - to do this manually:

+ +

+ Type "nmake -f makefile.mak" in the opensc\ dir to + compile. +

+ +

+ You need also perl and flex installed for the compile + process to complete successfully. +

+ +

+ No installation script has been provided, so you have + to do this manually: +

+
    -
  1. Copy opensc.conf to your Windows directory - (usually C:\WINDOWS or C:\WINNT). This is - optional.
    2. -
  2. Copy opensc.dll and opensc-pkcs11.dll to your - path.
    3. -
  3. If you want to use pkcs15-init.exe, make sure the - *.profile files in the pkcs15-init\ dir are in the - same directory as pkcs15-init.exe.
    4. +
  4. + Copy opensc.conf to your Windows directory (usually + C:\WINDOWS or C:\WINNT). This is optional. +
    5. + +
  5. + Copy opensc.dll and opensc-pkcs11.dll to your path. +
    6. + +
  6. + If you want to use pkcs15-init.exe, make sure the + *.profile files in the pkcs15-init\ dir are in the + same directory as pkcs15-init.exe. +
+

- Windows - with OpenSSL

+ Windows + with OpenSSL +
+
-

This adds extended functionality. E.g. the pkcs15-init - tool, pkcs11 hash mechanisms and more pkcs11 signature - mechs.

+ +

+ This adds extended functionality. E.g. the pkcs15-init + tool, PKCS #11 hash mechanisms and more PKCS #11 + signature mechanisms. +

+
    -
  1. download and compile the openssl sources from - http://www.openssl.org/source/
    2. -
  2. Add the inc32\ dir to your include path, the - out32dll\ to your lib path and your executable path - - - - -
    - 
    -set include=%include%;.....\inc32
-set lib=%lib%;.....\out32dll
-set path=%path%;....\out32dll
-
    -
    3. -
  3. In src/tools/Makefile.mak uncomment - pkcs15-init.exe in the "TARGETS" line (optionally) - and add libeay32.lib (and gdi32.lib) to the "link" - line
    4. -
  4. In src/libopensc/Makefile.mak add libeay32.lib - (and gdi32.lib) to the "link" line
    5. -
  5. In src/pkcs11/Makefile.mak add libeay32.lib (and - gdi32.lib) to the "link" line
    6. -
  6. In win32/Make.rules.mak add /DHAVE_OPENSSL to the - "COPTS" line
    7. +
  7. + Download and compile the OpenSSL sources from + + + http://www.openssl.org/source/ + +
    8. + +
  8. + Add the inc32\ dir to your include path, the + out32dll\ to your lib path and your executable path + + + + + + +
    + 
    +                        set include=%include%;.....\inc32
+                        set lib=%lib%;.....\out32dll
+                        set path=%path%;....\out32dll
+                                                                
+
    +
    +
    9. + +
  9. + In src/tools/Makefile.mak uncomment pkcs15-init.exe + in the "TARGETS" line (optionally) and add + libeay32.lib (and gdi32.lib) to the "link" line +
    10. + +
  10. + In src/libopensc/Makefile.mak add libeay32.lib (and + gdi32.lib) to the "link" line +
    11. + +
  11. + In src/pkcs11/Makefile.mak add libeay32.lib (and + gdi32.lib) to the "link" line +
    12. + +
  12. + In win32/Make.rules.mak add /DHAVE_OPENSSL to the + "COPTS" line +
-

To add the OpenSSL code to the DLLs (so you won't need - libeay32.dll anymore): statically compile OpenSSL and add - gdi32.lib next to libeay32.lib in the 3 Makefile.mak - files above.

+ +

+ To add the OpenSSL code to the DLLs (so you won't need + libeay32.dll anymore): statically compile OpenSSL and + add gdi32.lib next to libeay32.lib in the 3 + Makefile.mak files above. +

+

- - Chapter 6. Status

+ + Chapter 6. Status +
+
+

- Table of Contents + + Table of Contents +

+
- Card Status + + Card Status +
+
- Windows + + Windows +
+
- PKCS#11 Module in - Netscape and Mozilla + + PKCS #11 Module in Netscape and Mozilla +
+

- Card Status

+ Card Status +
+
+
- CryptoFlex + + CryptoFlex +
+
-

Support signing/decrypting, and - initialization

+

+ Support signing/decrypting, and initialization +

+
- Gemplus PK 4K, 8K, 16K + + Gemplus PK 4K, 8K, 16K +
+
-

Support signing/decrypting, and - initialization.

-

NOTE: You will not be able to initialize a - GemSafe cards - these card already have been - personalized by Gemplus, and you cannot erase them - or create new key files on them.

+

+ Support signing/decrypting, and initialization. +

+ +

+ NOTE: You will not be able to initialize a + GemSafe cards - these card already have been + personalized by Gemplus, and you cannot erase + them or create new key files on them. +

+
- Aladdin eToken PRO + + Aladdin eToken PRO +
+
-

Support signing/decrypting, and - initialization.

-

NOTE: CardOS only supports keys for decryption - or signing, but not both. If you create/store keys - with "--split-keys" OpenSC will work around this - limitation.

+

+ Support signing/decrypting, and initialization. +

+ +

+ NOTE: CardOS only supports keys for decryption or + signing, but not both. If you create/store keys + with "--split-keys" OpenSC will work around this + limitation. +

+
- Eutron CryptoIdendity - IT-SEC + + Eutron CryptoIdendity IT-SEC +
+
-

Support signing/decrypting, and - initialization.

-

NOTE: CardOS only supports keys for decryption - or signing, but not both. If you create/store keys - with "--split-keys" OpenSC will work around this - limitation.

+

+ Support signing/decrypting, and initialization. +

+ +

+ NOTE: CardOS only supports keys for decryption or + signing, but not both. If you create/store keys + with "--split-keys" OpenSC will work around this + limitation. +

+
- Micardo + + Micardo +
+
-

Supported - need to fill in the details

+

+ Supported - need to fill in the details +

+
- Miocos + + Miocos +
+
-

Supported - need to fill in the details

+

+ Supported - need to fill in the details +

+
- Setcos + + Setcos +
+
-

Supported - need to fill in the details

+

+ Supported - need to fill in the details +

+
- Tcos + + Tcos +
+
-

Supported - need to fill in the details

+

+ Supported - need to fill in the details +

+

- Windows

+ Windows +
+
-

At the moment only libopensc.dll and - opensc-pkcs11.dll, and most executables in the tools\ and - tests\ dir have been ported. They are tested on Win98, - WinNT, Win2000 and WinXP.

+ +

+ At the moment only libopensc.dll and opensc-pkcs11.dll, + and most executables in the tools\ and tests\ dir have + been ported. They are tested on Win98, WinNT, Win2000 + and WinXP. +

+

- PKCS#11 Module in - Netscape and Mozilla

+ PKCS #11 Module + in Netscape and Mozilla +
+
-

Netscape seems to show more information about the - security module than Mozilla. Otherwise all stuff is - untested.

-

Thread safety on Linux and Mac OS X: Netscape/Mozilla - uses the CKF_OS_LOCKING_OK flag in C_Initialize(). The - result is that the browser process doesn't end when - closing the browser, so you have to kill the process - yourself. (If the browser would do a C_Finalize, the - sc_pkcs11_free_lock() would be called and there wouldn't - be a problem.)

-

Therefore, we don't use the PTHREAD locking - mechanisms, even if they are requested. This seems to - work fine for Mozilla, BUT will cause problems for apps - that use multiple threads to access this lib - simultaneously.

-

If you do want to use OS threading, compile with - -DPKCS11_THREAD_LOCKING On Windows, no PTHREAD lib is - used and there the problem doesn't occur. So there the OS - locking is enabled.

+ +

+ Netscape seems to show more information about the + security module than Mozilla. Otherwise all stuff is + untested. +

+ +

+ Thread safety on Linux and Mac OS X: Netscape/Mozilla + uses the CKF_OS_LOCKING_OK flag in C_Initialize(). The + result is that the browser process doesn't end when + closing the browser, so you have to kill the process + yourself. (If the browser would do a C_Finalize, the + sc_pkcs11_free_lock() would be called and there + wouldn't be a problem.) +

+ +

+ Therefore, we don't use the PTHREAD locking mechanisms, + even if they are requested. This seems to work fine for + Mozilla, BUT will cause problems for apps that use + multiple threads to access this lib simultaneously. +

+ +

+ If you do want to use OS threading, compile with + -DPKCS11_THREAD_LOCKING On Windows, no PTHREAD lib is + used and there the problem doesn't occur. So there the + OS locking is enabled. +

+

- Chapter 7. Using - OpenSC

+ Chapter 7. Using + OpenSC +
+
+

- Table of Contents + + Table of Contents +

+
- OpenSC and - Netscape + + OpenSC and Netscape +
+
- OpenSC and - Mozilla + + OpenSC and Mozilla +
+
- OpenSC and - OpenSSL + + OpenSC and OpenSSL +
+
- OpenSC and - OpenSSH + + OpenSC and OpenSSH +
+
- Pluggable Authentication - Module + + Pluggable Authentication Module +
+
- eid based - authentication + + eid based authentication +
+
- ldap based - authentication + + LDAP based authentication +
+

- OpenSC and - Netscape

+ OpenSC and + Netscape +
+
+
    -
  1. Select menu: Communicator -> Tools -> - Security Info
    2. -
  2. Select Cryptographic Modules
    3. -
  3. Click: Add
    4. -
  4. Fill in module name: "OpenSC PKCS#11 Module" and - module file: - /path/to/opensc/lib/pkcs11/opensc-pkcs11.so
    5. +
  5. + Select menu: Communicator -> Tools -> + Security Info +
    6. + +
  6. + Select Cryptographic Modules +
    7. + +
  7. + Click: Add +
    8. + +
  8. + Fill in module name: "OpenSC PKCS #11 Module" and + module file: + /path/to/opensc/lib/pkcs11/opensc-pkcs11.so +
-

For proper operation, you also need to configure the - module: In the Crypthographic Modules dialog, select the - OpenSC card, and click on the "Config" button to the - right. Select the "Enable this token" radio button, and - select the "Publicly readable Certs" button.

-

This will ensure that netscape uses the card when - trying to display encrypted messages in netscape - messenger. Setting "Publicly readable Certs" will also - stop a pretty annoying habit of netscape which is to ask - for all PINs when browsing sites requiring client - authentication.

-

You should _not_ select the "RSA" button. If this - option is selected, netscape will try to use the card for - all public key operations, and will fail horribly.

-

FIXME: this is for which versions of netscape?

-
-
-
-
-
-

- OpenSC and - Mozilla

-
-
-
-
-
-
    -
  1. Make sure Personal Security Manager (PSM) is - installed (eg. mozilla-psm package is - installed).
    2. -
  2. Select menu: Edit -> Preferences
    3. -
  3. Select category: Privacy & Security -> - Certificates
    4. -
  4. Click: Manage Security Devices
    5. -
  5. Click: Load
    6. -
  6. Fill in module name: "OpenSC PKCS#11 Module" and - module file: - /path/to/opensc/lib/pkcs11/opensc-pkcs11.so
    7. -
-
-
-
-
-
-
-

- OpenSC and - OpenSSL

-
-
-
-
-

OpenSSL is a robust, full-featured toolkit - implementing the ssl protocols as well as a general - purpose cryptography library. It features a so called - engine interface to combine the toolkit with the - cryptographic abilities of some hardware.

-

OpenSC includes an engine for OpenSSL. This allowes to - use the OpenSSL library and command line utilities in - combination with smart card cryptography.

-

Here is an example how it works with the command line - tool - openssl. You need to load the - opensc engine first, and then can enter any command as - usual (e.g. create or sign a certificate).

-

Here is an example of how to load the engine.

- - - - -
- 
-aj@simulacron:~$ openssl
-OpenSSL> engine dynamic -pre
-SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so -pre ID:opensc
--pre LIST_ADD:1 -pre LOAD
-(dynamic) Dynamic engine loading support
-[Success]: SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
-[Success]: ID:opensc
-[Success]: LIST_ADD:1
-[Success]: LOAD
-Loaded: (opensc) opensc engine
-OpenSSL> 
-
-
-

-

A typical OpenSSL command might be to make a - certificate request: - req -engine opensc -new -key - - key - -keyform engine -out req.pem -text. See the - OpenSSL documentation for details.

-

- - - key - can specify the ID of a key in hex, - e.g. "45" would - be key 0x45. -

-

Actualy Opensc has even two engines for Openssl: - engine_opensc.soand - engine_pkcs11.so.

-

The opensc engine does only work with Opensc. It will - not work, if several applications try to use the smart - card at the same time or one applications tries to use - several smart cards at the same time. Or several - certificates or keys within one card. But for the simple - case (one app, one cert, one smart card) it is working - very fine.

-

The pkcs11 engine is very generic and flexible. It - will always work, even in complex situations involiving - several cards, keys, objects, certificates or concurrent - applications. Also it is fully based on pkcs11 and that - way it can use the Opensc pkcs11 library (and does so per - default), but it will work with any other pkcs11 library, - too.

-

To load the pkcs11 engine issue this command:

- - - - -
- 
-aj@simulacron:~$ openssl
-OpenSSL> engine dynamic -pre
-SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so -pre ID:pkcs11
--pre LIST_ADD:1 -pre LOAD -pre
-MODULE_PATH:/home/aj/opensc/lib/pkcs11/opensc-pkcs11.so
-(dynamic) Dynamic engine loading support
-[Success]: SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
-[Success]: ID:pkcs11
-[Success]: LIST_ADD:1
-[Success]: LOAD
-[Success]: MODULE_PATH:/home/aj/opensc/pkcs11/opensc-pkcs11.so
-Loaded: (pkcs11) pkcs11 engine
-OpenSSL> 
-
-
-

and then proceed as normal.

-

A typical OpenSSL command might be to make a - certificate request: - req -engine pkcs11 -new -key - - key - -keyform engine -out req.pem -text. See the - OpenSSL documentation for details.

+

- - key - has the format - [slot_<slotNr>][-][id_<keyID>], in which

-
-
    -
  • the optional slotNr indicates which pkcs11 slot - to take (starting from 0, which is also the - default)
    • -
  • keyID is the key ID in hex notation
    • -
-
-

Examples:

-
-
    -
  • id_45 => private key with ID = 0x45 in the - first 'suited' slot
    • -
  • slot_2-id_46 => private key with ID = 0x46 in - the third slot
    • -
-
-

-

For Windows, only the pkcs11 engine (not the opensc - engine) has been ported; use "engine_pkcs11" instead of - "engine_pkcs11.so".

+ For proper operation, you also need to configure the + module: In the Cryptographic Modules dialog, select the + OpenSC card, and click on the "Config" button to the + right. Select the "Enable this token" radio button, and + select the "Publicly readable Certs" button. +

+ +

+ This will ensure that Netscape uses the card when + trying to display encrypted messages in Netscape + messenger. Setting "Publicly readable Certs" will also + stop a pretty annoying habit of Netscape which is to + ask for all PINs when browsing sites requiring client + authentication. +

+ +

+ You should _not_ select the "RSA" button. If this + option is selected, Netscape will try to use the card + for all public key operations, and will fail horribly. +

+ +

+ FIXME: this is for which versions of Netscape? +

+

- OpenSC and - OpenSSH

+ OpenSC and + Mozilla +
+
-

Version 3.6.1p2 of OpenSSH needs a patch to compile - with OpenSC. You will find this patch in - src/openssh/.

-

When compiling OpenSSH you need to run configure like - this: - ./configure - --with-opensc=/path/to/opensc

-

You need to have a certificate on your smart card. A - key is not enough. Download the public key of your - certificate in Openssh format with this command: - ssh-keygen -D - - reader - [ - : - - certificate ID - ] > - - file -

-

Replace - - reader - with the number of the reader you want to use, - default it 0. - opensc-tool -lwill give you a - list of available readers. Add the certificate ID if you - need to select one. Default is 45. - pkcs11-tool -Owill give you a - list of available certificates and their IDs.

-

Then transfer the public key to the desired server and - add it to - ~/.ssh/authorized_keysas - usual.

-

To use a smart card with Openssh run - ssh -I - - reader - [ - : - - certificate ID - ]

-

You can also use the OpenSSH ssh-agent tool with - OpenSC. If you want to do so, use - ssh-add -s - - reader -

+ +
+
    +
  1. + Make sure Personal Security Manager (PSM) is + installed (eg. mozilla-psm package is installed). +
    2. + +
  2. + Select menu: Edit -> Preferences +
    3. + +
  3. + Select category: Privacy & Security -> + Certificates +
    4. + +
  4. + Click: Manage Security Devices +
    5. + +
  5. + Click: Load +
    6. + +
  6. + Fill in module name: "OpenSC PKCS #11 Module" and + module file: + /path/to/opensc/lib/pkcs11/opensc-pkcs11.so +
    7. +
+
+

- Pluggable - Authentication Module

+ OpenSC and + OpenSSL +
+
-

Pluggable authantication modules or pam is the default - way under linux and other unix operating systems to - configure authentication. OpenSC includes a module to - allow smart card based authentication: pam_opensc.

-

The following options are recognized:

-
-
-
- debug -
-
log more debugging info
-
- audit -
-
a little more extreme than debug
-
- use_first_pass -
-
don't prompt the user for passwords, take them - from PAM_ items insteat
-
- try_first_pass -
-
don't prompt the user for passwords unless - PAM_(OLD)AUTHTOK in unsed
-
- use_authtok -
-
require PAM_AUTHTOK set, use it, fail - otherwise
-
- set_pass -
-
set the PAM_ item swith the passwords used by - this module
-
- nodelay -
-
used to prevent failed authentication resulting - in a delay of about 1 second.
-
- auth_method=X -
-
choose either pkcs15-ldap or pkcs15-eid - authentication. pkcs15-eid is the default.
-
-
+ +

+ OpenSSL is a robust, full-featured toolkit implementing + the SSL protocols as well as a general purpose + cryptography library. It features a so called engine + interface to combine the toolkit with the cryptographic + abilities of some hardware. +

+ +

+ OpenSC includes an engine for OpenSSL. This allows to + use the OpenSSL library and command line utilities in + combination with smart card cryptography. +

+ +

+ Here is an example how it works with the command line + tool + + + openssl + . You need to load the opensc engine first, and + then can enter any command as usual (e.g. create or + sign a certificate). +

+ +

+ Here is an example of how to load the engine. +

+ + + + + +
+ 
+                  aj@simulacron:~$ openssl
+                  OpenSSL> engine dynamic -pre
+                  SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
+                  -pre ID:opensc -pre LIST_ADD:1 -pre LOAD
+                  (dynamic) Dynamic engine loading support
+                  [Success]:
+                  SO_PATH:/home/aj/opensc/lib/opensc/engine_opensc.so
+                  [Success]: ID:opensc
+                  [Success]: LIST_ADD:1
+                  [Success]: LOAD
+                  Loaded: (opensc) opensc engine
+                  OpenSSL> 
+                                                  
+
+
+

-

Generic options:

-
-
-
- -h -
-
Show help
-
- -r reader -
-
Reader name (FIXME: not number?)
-
-
-

-
-
-
-
-

- eid based - authentication

-
-
-
-
-

This is the default authentication method. Create a - directory - .eidin your home directory - and copy your PEM encoded certificat to the file - - .eid/authorized_certificates.

-

Note: - pkcs15-tool -cwill show you all - certificates and their ID, - pkcs15-tool -r ID -o - ~/.eid/authorized_certificateswill save the - certificate + +

+ A typical OpenSSL command might be to make a + certificate request: + + + req -engine opensc -new -key + + + + key + + -keyform engine -out req.pem -text + . See the OpenSSL documentation for details. +

+ +

+ - + - ID - to that file.

+ + key + + can specify the ID of a key in hex, - e.g. "45" + would be key 0x45. - +

+ +

+ Actually OpenSC has even two engines for OpenSSL: + + + engine_opensc.so + and + + + engine_pkcs11.so + . +

+ +

+ The opensc engine does only work with OpenSC. It will + not work, if several applications try to use the smart + card at the same time or one applications tries to use + several smart cards at the same time. Or several + certificates or keys within one card. But for the + simple case (one app, one cert, one smart card) it is + working very fine. +

+ +

+ The PKCS #11 engine is very generic and flexible. It + will always work, even in complex situations involving + several cards, keys, objects, certificates or + concurrent applications. Also it is fully based on PKCS + #11 and that way it can use the OpenSC PKCS #11 library + (and does so by default), but it will work with any + other PKCS #11 library, too. +

+ +

+ To load the PKCS #11 engine, issue this command: +

+ + + + + +
+ 
+                  aj@simulacron:~$ openssl
+                  OpenSSL> engine dynamic -pre
+                  SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
+                  -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre
+                  MODULE_PATH:/home/aj/opensc/lib/pkcs11/opensc-pkcs11.so
+                  (dynamic) Dynamic engine loading support
+                  [Success]:
+                  SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so
+                  [Success]: ID:pkcs11
+                  [Success]: LIST_ADD:1
+                  [Success]: LOAD
+                  [Success]:
+                  MODULE_PATH:/home/aj/opensc/pkcs11/opensc-pkcs11.so
+                  Loaded: (pkcs11) pkcs11 engine
+                  OpenSSL> 
+                                                  
+
+
+ +

+ and then proceed as normal. +

+ +

+ A typical OpenSSL command might be to make a + certificate request: + + + req -engine pkcs11 -new -key + + + + key + + -keyform engine -out req.pem -text + . See the OpenSSL documentation for details. +

+ +

+ + + key + + has the format + [slot_<slotNr>][-][id_<keyID>], in which +

+ +
+
    +
  • + the optional slotNr indicates which PKCS #11 slot + to take (starting from 0, which is also the + default) +
    • + +
  • + keyID is the key ID in hex notation +
    • +
+ +

+ Examples: +

+ +
+
    +
  • + id_45 => private key with ID = 0x45 in the first + 'suited' slot +
    • + +
  • + slot_2-id_46 => private key with ID = 0x46 in + the third slot +
    • +
+
+ +

+ +

+ For Windows, only the PKCS #11 engine (not the OpenSC + engine) has been ported; use "engine_pkcs11" instead of + "engine_pkcs11.so". +

+
+ +
+
+
+
+

+ OpenSC and + OpenSSH +

+
+
+ +
+
+ +

+ Version 3.6.1p2 of OpenSSH needs a patch to compile + with OpenSC. You will find this patch in src/openssh/. +

+ +

+ When compiling OpenSSH you need to run configure like + this: + + + ./configure --with-opensc=/path/to/opensc + +

+ +

+ You need to have a certificate on your smart card. A + key is not enough. Download the public key of your + certificate in Openssh format with this command: + + + ssh-keygen -D + + + + reader + + [ + + + : + + + + certificate ID + + + ] > + + + + file + + + +

+ +

+ Replace + + + + reader + + with the number of the reader you want to use, + default it 0. + + + opensc-tool -l + will give you a list of available readers. Add the + certificate ID if you need to select one. Default is + 45. + + + pkcs11-tool -O + will give you a list of available certificates and + their IDs. +

+ +

+ Then transfer the public key to the desired server and + add it to + + + ~/.ssh/authorized_keys + as usual. +

+ +

+ To use a smart card with Openssh run + + + ssh -I + + + + reader + + [ + + + : + + + + certificate ID + + + ] + +

+ +

+ You can also use the OpenSSH ssh-agent tool with + OpenSC. If you want to do so, use + + + ssh-add -s + + + + reader + + + +

+
+ +
+
+
+
+

+ Pluggable + Authentication Module +

+
+
+ +
+
+ +

+ Pluggable authentication modules (PAM) is the default + way under Linux and other Unix operating systems to + configure authentication. OpenSC includes a module to + allow smart card based authentication: pam_opensc. +

+ +

+ The following options are recognized: +

+ +
+
+
+ + debug + +
+ +
+ log more debugging info +
+ +
+ + audit + +
+ +
+ a little more extreme than debug +
+ +
+ + use_first_pass + +
+ +
+ don't prompt the user for passwords, take them from + PAM_ items instead +
+ +
+ + try_first_pass + +
+ +
+ don't prompt the user for passwords unless + PAM_(OLD)AUTHTOK in used +
+ +
+ + use_authtok + +
+ +
+ require PAM_AUTHTOK set, use it, fail otherwise +
+ +
+ + set_pass + +
+ +
+ set the PAM_ item with the passwords used by this + module +
+ +
+ + nodelay + +
+ +
+ used to prevent failed authentication resulting in + a delay of about 1 second. +
+ +
+ + auth_method=X + +
+ +
+ choose either pkcs15-ldap or pkcs15-eid + authentication. pkcs15-eid is the default. +
+
+
+ +

+ +

+ Generic options: +

+ +
+
+
+ + -h + +
+ +
+ Show help +
+ +
+ + -r reader + +
+ +
+ Reader name (FIXME: not number?) +
+
+
+ +

+

- ldap based - authentication

+ eid based + authentication +
+
-

Setting auth_method to pkcs15-ldap will enable ldap - based authenticaton. These options are supported:

+ +

+ This is the default authentication method. Create a + directory + + + .eid + in your home directory and copy your PEM encoded + certificate to the file + + + .eid/authorized_certificates + . +

+ +

+ Note: + + + pkcs15-tool -c + will show you all certificates and their ID, + + + pkcs15-tool -r ID -o ~/.eid/authorized_certificates + will save the certificate + + + + ID + + to that file. +

+
+ +
+
+
+
+

+ LDAP based + authentication +

+
+
+ +
+
+ +

+ Setting auth_method to pkcs15-ldap will enable LDAP + based authentication. These options are supported: +

+
- -L ldap.conf + + -L ldap.conf +
-
Configuration file to load
+ +
+ Configuration file to load +
+
- -A entry + + -A entry +
-
Add new entry
+ +
+ Add new entry +
+
- -E entry + + -E entry +
-
Set current entry
+ +
+ Set current entry +
+
- -H hostname + + -H hostname +
-
hostname of ldap server
+ +
+ hostname of LDAP server +
+
- -P port + + -P port +
-
port or ldap server
+ +
+ port or LDAP server +
+
- -S scope + + -S scope +
-
scope of ldap server
+ +
+ scope of LDAP server +
+
- -b binddn + + -b binddn +
-
binddn for ldap connection
+ +
+ binddn for LDAP connection +
+
- -p passwd + + -p passwd +
-
password for ldap bind
+ +
+ password for LDAP bind +
+
- -B base + + -B base +
-
base for ldap bind
+ +
+ base for LDAP bind +
+
- -a attributes + + -a attributes +
-
attributes to fetch
+ +
+ attributes to fetch +
+
- -f filter + + -f filter +
-
filter in ldap search
+ +
+ filter in LDAP search +
-

FIXME: provide an example of ldap data structure, - config file etc.

+ +

+ FIXME: provide an example of LDAP data structure, + config file etc. +

+

- Chapter 8. The - OpenSC PKCS11 library

+ Chapter 8. The + OpenSC PKCS #11 library +
+
+

- Table of Contents + + Table of Contents +

+
- What is PKCS11 + + What is PKCS #11 +
+
- Virtual slots + + Virtual slots +
+

- What is - PKCS11

+ What is PKCS #11 +
+
-

PKCS11 is a standard API for accessing cryptographic - tokens such as smart cards, Hardware Security Modules, - ... It contains functions like C_GetSlotList(), - C_OpenSession(), C_FindObjects(), C_Login(), C_Decrypt(), - ...

-

Some core concepts of pkcs11 are:

+ +

+ + PKCS #11 + is a standard API for accessing cryptographic + tokens such as smart cards, Hardware Security Modules, + ... It contains functions like C_GetSlotList(), + C_OpenSession(), C_FindObjects(), C_Login(), + C_Decrypt(), ... +

+ +

+ Some core concepts of PKCS #11 are: +

+
    -
  • slot: the place in which a smart card can be put. - Usually this corresponds with a card reader (but: see - below, Virtual slots).
    • -
  • token: the thing that is put in a slot. Usually - this corresponds with a smart card (but: see below, - virtual slots).
    • -
  • object: a key, a certificate, some data, ... Is - either a token object (if it resides on the card) or - a session object (if it doesn't reside on the card, - e.g. a certificate given to the pkcs11 library to do - a verification).
    • -
  • session: before you can do anything with a token, - you have to open a session on it.
    • -
  • operation: a signature, decryption, digest, ... - operation, that can consist of multiple function - calls. Example: C_SignInit(), C_SignUpdate(), - C_SignFinal(); here the first function starts the - operation, the third one ends it. Only one operation - can be done in the same session, but multiple - sessions can be opened on the same token.
    • +
  • + slot: the place in which a smart card can be put. + Usually this corresponds with a card reader (but: + see below, Virtual slots). +
    • + +
  • + token: the thing that is put in a slot. Usually + this corresponds with a smart card (but: see below, + virtual slots). +
    • + +
  • + object: a key, a certificate, some data, ... Is + either a token object (if it resides on the card) + or a session object (if it doesn't reside on the + card, e.g. a certificate given to the PKCS #11 + library to do a verification). +
    • + +
  • + session: before you can do anything with a token, + you have to open a session on it. +
    • + +
  • + operation: a signature, decryption, digest, ... + operation, that can consist of multiple function + calls. Example: C_SignInit(), C_SignUpdate(), + C_SignFinal(); here the first function starts the + operation, the third one ends it. Only one + operation can be done in the same session, but + multiple sessions can be opened on the same token. +
+

+

- Virtual slots

+ Virtual slots +
+
-

Per token, only 2 PINs can be given: the SO (Security - Officer) PIN and the user PIN. However, smart cards can - have more than 1 user PIN. A way to this solve problem is - to have multiple 'virtual' slots, as explained in - appendix D of the pkcs11 standard. So per physical - reader, you have a number of virtual slots. If you insert - a card in the reader, a token will appear in all the - virtual slots, and each token will contain 1 PIN along - with the private keys it protects and certificates - corresponding to those private keys.

-

Because OpenSC supports multiple cards, it is not - known in advance how many PINs a smart card will have. - Therefore, a default number of 4 virtual slots is used. - You can change this default in the pkcs11 section of - opensc.conf: num_slots.

-

Opensc implements the following behaviour: for each - PIN, its private keys and corresponding certs, there is 1 - virtual slot allocated. If there are any objects left, - they are put in the next free virtual slot. And if there - are some virtual slots left, an 'empty' token is 'put' in - them; on this empty token a PIN and data can then be put. - If you find this too confusing, you can hide empty tokens - with the hide_empty_tokens option in the config file.

-

Example: Take a card with 2 PINs. Each PIN protects a - private key and each private key has a corresponding cert - chain. And then there are 3 other roots certs that have - nothing to do with the other data. Now if num_slots = 4, - hide_empty_tokens = false; and if you put the card your - second card reader, you'll get the following:

+ +

+ Per token, only 2 PINs can be given: the SO (Security + Officer) PIN and the user PIN. However, smart cards can + have more than 1 user PIN. A way to this solve problem + is to have multiple 'virtual' slots, as explained in + appendix D of the + + + PKCS #11 standard + . So per physical reader, you have a number of + virtual slots. If you insert a card in the reader, a + token will appear in all the virtual slots, and each + token will contain 1 PIN along with the private keys it + protects and certificates corresponding to those + private keys. +

+ +

+ Because OpenSC supports multiple cards, it is not known + in advance how many PINs a smart card will have. + Therefore, a default number of 4 virtual slots is used. + You can change this default in the pkcs11 section of + opensc.conf: num_slots. +

+ +

+ OpenSC implements the following behaviour: for each + PIN, its private keys and corresponding certs, there is + 1 virtual slot allocated. If there are any objects + left, they are put in the next free virtual slot. And + if there are some virtual slots left, an 'empty' token + is 'put' in them; on this empty token a PIN and data + can then be put. If you find this too confusing, you + can hide empty tokens with the hide_empty_tokens option + in the config file. +

+ +

+ Example: Take a card with 2 PINs. Each PIN protects a + private key and each private key has a corresponding + cert chain. And then there are 3 other roots certs that + have nothing to do with the other data. Now if + num_slots = 4, hide_empty_tokens = false; and if you + put the card your second card reader, you'll get the + following: +

+
    -
  • token in slot 4: PIN 1, key 1, cert chain 1
    • -
  • token in slot 5: PIN 2, key 2, cert chain 2
    • -
  • token in slot 6: the 3 other root certs
    • -
  • token in slot 7: no data
    • +
  • + token in slot 4: PIN 1, key 1, cert chain 1 +
    • + +
  • + token in slot 5: PIN 2, key 2, cert chain 2 +
    • + +
  • + token in slot 6: the 3 other root certs +
    • + +
  • + token in slot 7: no data +
-

If hide_empty_tokens would have been true, slot 7 - wouldn't show a token.

-

Note: if in the example the 2 cert chain would have - common certificates, those certificates would appear in - the tokens in slots 4 and 5. (Which would cause a problem - if those certs were deleted, this hasn't been solved yet - in OpenSC).

-

Another good-to-know: the number of virtual slots has - been hard-coded (it is 8 at the moment). So if num_slots - = 4, only the first 2 readers will be visible. Or if - you'd put num_slots to 3, the first 2 readers will have 3 - virtual slots and the third reader will have 2.

+ +

+ If hide_empty_tokens would have been true, slot 7 + wouldn't show a token. +

+ +

+ Note: if in the example the 2 cert chain would have + common certificates, those certificates would appear in + the tokens in slots 4 and 5. (Which would cause a + problem if those certs were deleted, this hasn't been + solved yet in OpenSC). +

+ +

+ Another good-to-know: the number of virtual slots has + been hard-coded (it is 8 at the moment). So if + num_slots = 4, only the first 2 readers will be + visible. Or if you'd put num_slots to 3, the first 2 + readers will have 3 virtual slots and the third reader + will have 2. +

+

- Chapter 9. What - needs to be done

+ Chapter 9. What + needs to be done +
+
+

- Table of Contents + + Table of Contents +

+
- Windows + + Windows +
+ 
-* Debian packaging
-* GUI applications
-* Add support for EMV and GSM (anyone?)
-
+ * Debian packaging + * GUI applications + * Add support for EMV and GSM (anyone?) + +
+ 
-* Pin pad support
-* Merge DODF patches (mostly done)
-* put generic PEM encoding/decoding functions into libopensc?
-* Merge pkcs11 proxy from Zetes
-* pkcs11: support decrypt for those cards that have it
-* pkcs11: make sure all PIN ops work through pkcs11
-* pkcs11: unblock pins: check for unblock pins in AODF
-* all: support for RSA-PSS
-* pkcs15-init: support SOPIN on Cryptoflex
-* pkcs15-init: use max. possible usage by default
-* pkcs15-init: during keygen, make sure the pubkey usage is right
-* pkcs15-init: when using an unblock PIN, write an AODF entry for
-it
-  (alternatively: set unblockDisabled flag for those PINs that have
-no PUK?)
-* pkcs15: fix sc_pkcs15_change_reference_data; add unblock function
-* pkcs11: make sure all PIN ops work through pkcs11
-
+ * Pin pad support + * Merge DODF patches (mostly done) + * put generic PEM encoding/decoding functions into + libopensc? + * Merge pkcs11 proxy from Zetes + * pkcs11: support decrypt for those cards that have + it + * pkcs11: make sure all PIN ops work through pkcs11 + * pkcs11: unblock pins: check for unblock pins in + AODF + * all: support for RSA-PSS + * pkcs15-init: support SOPIN on Cryptoflex + * pkcs15-init: use max. possible usage by default + * pkcs15-init: during keygen, make sure the pubkey + usage is right + * pkcs15-init: when using an unblock PIN, write an + AODF entry for it + (alternatively: set unblockDisabled flag for + those PINs that have no PUK?) + * pkcs15: fix sc_pkcs15_change_reference_data; add + unblock function + * pkcs11: make sure all PIN ops work through pkcs11 + +
+

- Windows

+ Windows +
+
-

Other parts of OpenSC be should ported as well. Also - we should implement native Win32 APIs such as CryptoAPI - Provider, some login stuff and ActiveX plugin for - Explorer to do the signing.

+ +

+ Other parts of OpenSC be should ported as well. Also we + should implement native Win32 APIs such as CryptoAPI + Provider, some login stuff and ActiveX plugin for + Internet Explorer to do the signing. +

+

- - Chapter 10. Troubleshooting

+ + Chapter 10. Troubleshooting +
+
-

A mailing-list has been set up for support and - discussion about the OpenSC project. Additional info is - available at OpenSC web site.

+ +

+ A mailing list has been set up for support and discussion + about the OpenSC project. Additional info is available at + the + + + OpenSC web site + . +

+

- - Chapter 11. Resources

+ + Chapter 11. Resources +
+
-

See the OpenSC web site at - - http://www.opensc.org/

-

Information about Assuan and project Ägypten: - - http://www.gnupg.org/aegypten/

+ +

+ See the OpenSC web site at + + + http://www.opensc.org/ + +

+ +

+ Information about Assuan and project Ägypten: + + + http://www.gnupg.org/aegypten/ + +

+

- - Chapter 12. Signer

+ + Chapter 12. Signer +
+
+

- Table of Contents + + Table of Contents +

+
- Building and - Installing libopensc + + Building and installing the OpenSC Signer +
-

OpenSC Signer is a Netscape plugin that will generate - digital signatures using facilities on PKI-capable - smartcards.

+ +

+ OpenSC Signer is a Netscape plugin that will generate + digital signatures using facilities on PKI-capable smart + cards. +

+

- Building and - Installing libopensc

+ Building and + installing the OpenSC Signer +
+
-

You should specify your plugin directory with: - $ configure --with-plugin-dir= - - <directory> -

-

Common plugin directories are /usr/lib/mozilla/plugins - and /usr/lib/netscape/plugins.

-

See the INSTALL file for more instructions.

-

NOTE: PIN code dialog is done through libassuan from - Project Ägypten. If you don't have it installed already, - download it from the link below.

+ +

+ You should specify your plugin directory with: + + + $ configure --with-plugin-dir= + + + + <directory> + + + +

+ +

+ Common plugin directories are /usr/lib/mozilla/plugins + and /usr/lib/netscape/plugins. +

+ +

+ See the INSTALL file for more instructions. +

+ +

+ NOTE: PIN code dialog is done through libassuan from + Project Ägypten. If you don't have it installed + already, download it from the link below. +

+

- Chapter 13. A - few hints on docbook documents

+ Chapter 13. A + few hints on DocBook documents +
+
-

This document is maintained as docbook xml document. - Here are some hints and links for newcomers.

-

This document is written in XML not SGML. To convert it, - use a XSL stylesheet, not an DSSSL stylesheet. Ignore all - tools and webpages talking about SGML or DSSSL, those talk - about legecy technology no longer used and no longer up to - date.

+

- The Docbook - Projectat Sourceforge has the XSL stylshet used to - convert this XML document to other formats.

+ This document is maintained as DocBook XML document. Here + are some hints and links for newcomers. +

+

- Docbook, - the definite Guide (O'Reilly Book)documents Docbook, is - very handy as reference and available Online for free.

+ This document is written in XML not SGML. To convert it, + use a XSL stylesheet, not an DSSSL stylesheet. Ignore all + tools and web pages talking about SGML or DSSSL, those + talk about legacy technology no longer used and no longer + up to date. +

+

- Online Book on Docbook, XML and XSLis a - book with a greate introduction on how to create a - document, how to convert it, where to get the software, - tools and everything. It you a fast road to editing this - document, look at this book.

-

THis document might be ugly. If you know html, please - help us to improve it. Some stuff can be tuned in the xsl - stylesheet (see - Reference for the HTML stylesheet - parameters), but most stuff can be improved via CSS - styles. We need help on this !

+ + DocBook Open Repository project + at SourceForge has the XSL stylesheet used to convert + this XML document to other formats. +

+ +

+ + DocBook: The Definitive Guide (O'Reilly Book) + documents DocBook, is very handy as reference and + available online for free. +

+ +

+ + DocBook XSL: The Complete Guide + is a book with a great introduction on how to create + a document, how to convert it, where to get the software, + tools and everything. It you a fast road to editing this + document, look at this book. +

+ +

+ This document might be ugly. If you know html, please + help us to improve it. Some stuff can be tuned in the XSL + stylesheet (see + + + Reference for the HTML stylesheet parameters + ), but most stuff can be improved via CSS styles. We + need help on this ! +

diff --git a/docs/opensc.xml b/docs/opensc.xml index 1c63b955..893c25e7 100644 --- a/docs/opensc.xml +++ b/docs/opensc.xml @@ -14,14 +14,14 @@ Introduction - libopensc is a library for accessing SmartCard devices + libopensc is a library for accessing smart card devices using PC/SC Lite middleware package. It is also the core library of the OpenSC project. Basic functionality (e.g. SELECT FILE, READ BINARY) should - work on any ISO 7816-4 compatible SmartCard. Encryption - and decryption using private keys on the SmartCard is - at the moment possible only with PKCS#15 compatible - cards, such as the FINEID (Finnish Electronic IDentity) + work on any ISO 7816-4 compatible smart card. Encryption + and decryption using private keys on the smart card is + at the moment possible only with PKCS #15 compatible + cards, such as the FINEID (Finnish electronic ID card) card manufactured by Setec. @@ -55,6 +55,10 @@ Nils Larsch larsch@trustcenter.de + + Ville Skyttä + + Kevin Stefanik kstef@mtppi.org @@ -150,8 +154,8 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA OpenSC is a large toolkit. The main building block is the opensc library. It has three layers of code, each with several drivers in it. - Other libraries are the pkcs11 module, - a pam module, two engines for openssl. + Other libraries are the PKCS #11 module, + a PAM module, two engines for OpenSSL. In addition there are several tools to test and use these tools and libraries. @@ -160,7 +164,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA Purpose of this chapter is to give an overview of the inner workings of the opensc library, to give a short presentation what the other - libraries do, and finaly what the opensc toolchest + libraries do, and finally what the opensc toolchest has to offer. Each tool has it's own man page, each library it's own section in this document. @@ -170,10 +174,10 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA libopensc is the basic library used by - everthing else. It offer basic + everything else. It offer basic functionality like talking to smart cards, but also advances functions - like generating rsa keys on a smart card. + like generating RSA keys on a smart card. @@ -202,7 +206,7 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA In a perfect world all smart cards would implement ISO 7816 standard, and thus accept the same commands - and give the same answers. Unfortunatly + and give the same answers. Unfortunately most cards have their own commands, syntax and responses. The card modules in libopensc implement these different @@ -213,8 +217,8 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA pkcs15init - Smart cards usualy have a file system. - To store or create keys or certiticates + Smart cards usually have a file system. + To store or create keys or certificates on a smart card one needs to format the card, create directories and objects and set permissions in a secure way. @@ -227,26 +231,26 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA - pkcs15 framework + PKCS #15 framework - PKCS#15 is the standard on how to + PKCS #15 is the standard on how to store certificates and keys on a smart card or crypto token. But many - vendors have their own proprietory + vendors have their own proprietary mechanism for storing these informations, for example in different directories. OpenSC implements - the PKCS#15 standard, but there is + the PKCS #15 standard, but there is also an emulation module for a slightly incompatible storage mechanism in the works. It should be possible to implement a - completely differennt framework - for compatiblity with a non - pkcs#15 way of storing and accessing + completely different framework + for compatibility with a non + PKCS #15 way of storing and accessing keys and certificates. @@ -257,42 +261,42 @@ Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA The reader layer - PC/SC-Lite is well known as smart card + PC/SC Lite is well known as smart card middleware. It interacts with drivers for - the smart card readers on the buttom, + the smart card readers on the bottom, and with smart card applications on the top. - OpenSC can use PC/SC-Lite via the pcsc + OpenSC can use PC/SC Lite via the pcsc reader module, but also supports a number of alternatives. - PC/SC is a standard with interfaces betweens + PC/SC is a standard with interfaces between applications, a resource manager and drivers for smart card readers. This standard is very popular on the Windows operating System. - The documents are available from the + The documents are available from . - PC/SC-Lite is an implementation of the - PC/SC standard for linux, Unix, Mac OS X + PC/SC Lite is an implementation of the + PC/SC standard for Linux, Unix, Mac OS X and Windows by David Corcoran corcoran@linuxnet.com. The software is available with full source code and available for free. To download the software, please visit the website of the Movement - for the use of smart cards in a linux + for the use of smart cards in a Linux environment (M.U.S.C.L.E.) at . - To install OpenSC with support for PC/SC-Lite, - please install PC/SC-Lite first. Then configure - OpenSC to use PC/SC-Lite and specify the - location where PC/SC-Lite is installed like + To install OpenSC with support for PC/SC Lite, + please install PC/SC Lite first. Then configure + OpenSC to use PC/SC Lite and specify the + location where PC/SC Lite is installed like this: $ cd opensc-0.8.0 @@ -304,8 +308,8 @@ $ ./configure --with-pcsclite=/path/to/pcsclite OpenCT is a new framework for accessing smart cards, card readers and card terminals. It was written from scratch, already includes - all drivers, and is very lightwight. OpenCT - is available for linux, but if you want to + all drivers, and is very lightweight. OpenCT + is available for Linux, but if you want to use it on other Unix or BSD operating systems, please ask for help on the opensc-devel mailing list. @@ -313,10 +317,10 @@ $ ./configure --with-pcsclite=/path/to/pcsclite OpenCT is open source software. As such - it is availble with full source code for + it is available with full source code for free. OpenCT is a software companion - to OpenSC and the prefered way of accessing - smart cards under linux. OpenCT is available + to OpenSC and the preferred way of accessing + smart cards under Linux. OpenCT is available from the OpenSC website and questions go to the @@ -333,16 +337,20 @@ $ ./configure --with-pcsclite=/path/to/pcsclite Then configure OpenSC to use OpenCT and specify the location where OpenCT is installed like this: + +$ cd opensc-0.8.0 +$ ./configure --with-openct=/path/to/openct + Usbtoken is a small driver for usb crypto devices only. It does not need any other helper software and is included in OpenSC for - convinience. However Usbtoken is deprecated, + convenience. However Usbtoken is deprecated, the new OpenCT software is now the recommended way to access usb crypto tokens. Usbtoken - is no longer activly developed, but bugs are + is no longer actively developed, but bugs are still fixed and help is provided on the OpenSC mailing list at opensc-devel@opensc.org. @@ -370,9 +378,9 @@ $ ./configure --enable-usbtoken multiuser multitasking applications. However CT-API is still quite popular, and many smart card readers have drivers - in CT-API format even for linux. It is + in CT-API format even for Linux. It is recommended to use these drivers if - the PC/SC-Lite middleware described above. + the PC/SC Lite middleware described above. @@ -417,7 +425,7 @@ $ ./configure --enable-usbtoken You need also perl and flex installed for the - compile process to complete succesfully. + compile process to complete successfully. @@ -451,13 +459,13 @@ $ ./configure --enable-usbtoken This adds extended functionality. E.g. the - pkcs15-init tool, pkcs11 hash mechanisms and - more pkcs11 signature mechs. + pkcs15-init tool, PKCS #11 hash mechanisms and + more PKCS #11 signature mechanisms. - download and compile the openssl + Download and compile the OpenSSL sources from @@ -619,7 +627,7 @@ set path=%path%;....\out32dll
- PKCS#11 Module in Netscape and Mozilla + PKCS #11 Module in Netscape and Mozilla Netscape seems to show more information about @@ -676,36 +684,36 @@ set path=%path%;....\out32dll - Fill in module name: "OpenSC PKCS#11 Module" + Fill in module name: "OpenSC PKCS #11 Module" and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so For proper operation, you also need to configure the - module: In the Crypthographic Modules dialog, select + module: In the Cryptographic Modules dialog, select the OpenSC card, and click on the "Config" button to the right. Select the "Enable this token" radio button, and select the "Publicly readable Certs" button. - This will ensure that netscape uses the card when - trying to display encrypted messages in netscape + This will ensure that Netscape uses the card when + trying to display encrypted messages in Netscape messenger. Setting "Publicly readable Certs" will also - stop a pretty annoying habit of netscape which is to + stop a pretty annoying habit of Netscape which is to ask for all PINs when browsing sites requiring client authentication. You should _not_ select the "RSA" button. If this - option is selected, netscape will try to use the card + option is selected, Netscape will try to use the card for all public key operations, and will fail horribly. - FIXME: this is for which versions of netscape? + FIXME: this is for which versions of Netscape?
@@ -737,7 +745,7 @@ set path=%path%;....\out32dll - Fill in module name: "OpenSC PKCS#11 Module" + Fill in module name: "OpenSC PKCS #11 Module" and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so @@ -748,7 +756,7 @@ set path=%path%;....\out32dll OpenSSL is a robust, full-featured toolkit - implementing the ssl protocols as well as + implementing the SSL protocols as well as a general purpose cryptography library. It features a so called engine interface to combine the toolkit with the cryptographic @@ -757,7 +765,7 @@ set path=%path%;....\out32dll OpenSC includes an engine for OpenSSL. This - allowes to use the OpenSSL library and command line + allows to use the OpenSSL library and command line utilities in combination with smart card cryptography. @@ -796,13 +804,13 @@ OpenSSL> - - Actualy Opensc has even two engines for Openssl: + Actually OpenSC has even two engines for OpenSSL: engine_opensc.so and engine_pkcs11.so. - The opensc engine does only work with Opensc. + The opensc engine does only work with OpenSC. It will not work, if several applications try to use the smart card at the same time or one applications tries to use several @@ -813,17 +821,18 @@ OpenSSL> - The pkcs11 engine is very generic and flexible. + The PKCS #11 engine is very generic and flexible. It will always work, even in complex situations - involiving several cards, keys, objects, certificates + involving several cards, keys, objects, certificates or concurrent applications. Also it is fully based - on pkcs11 and that way it can use the Opensc - pkcs11 library (and does so per default), but - it will work with any other pkcs11 library, too. + on PKCS #11 and that way it can use the OpenSC + PKCS #11 library (and does so by default), but + it will work with any other PKCS #11 library, + too. - To load the pkcs11 engine issue this command: + To load the PKCS #11 engine, issue this command: aj@simulacron:~$ openssl OpenSSL> engine dynamic -pre SO_PATH:/home/aj/opensc/lib/opensc/engine_pkcs11.so -pre ID:pkcs11 -pre LIST_ADD:1 -pre LOAD -pre MODULE_PATH:/home/aj/opensc/lib/pkcs11/opensc-pkcs11.so @@ -849,7 +858,7 @@ OpenSSL> key has the format ][-][id_]]]>, in which - the optional slotNr indicates which pkcs11 slot to take + the optional slotNr indicates which PKCS #11 slot to take (starting from 0, which is also the default) @@ -868,7 +877,7 @@ OpenSSL> - For Windows, only the pkcs11 engine (not the opensc engine) has been ported; + For Windows, only the PKCS #11 engine (not the OpenSC engine) has been ported; use "engine_pkcs11" instead of "engine_pkcs11.so". @@ -928,8 +937,8 @@ OpenSSL> Pluggable Authentication Module - Pluggable authantication modules or pam is - the default way under linux and other unix + Pluggable authentication modules (PAM) is + the default way under Linux and other Unix operating systems to configure authentication. OpenSC includes a module to allow smart card based authentication: pam_opensc. @@ -950,12 +959,12 @@ OpenSSL> use_first_pass - don't prompt the user for passwords, take them from PAM_ items insteat + don't prompt the user for passwords, take them from PAM_ items instead try_first_pass - don't prompt the user for passwords unless PAM_(OLD)AUTHTOK in unsed + don't prompt the user for passwords unless PAM_(OLD)AUTHTOK in used @@ -965,7 +974,7 @@ OpenSSL> set_pass - set the PAM_ item swith the passwords used by this module + set the PAM_ item with the passwords used by this module @@ -1003,7 +1012,7 @@ OpenSSL> method. Create a directory .eid in your home directory and copy your PEM encoded - certificat to the file + certificate to the file .eid/authorized_certificates. @@ -1019,11 +1028,11 @@ OpenSSL>
- ldap based authentication + LDAP based authentication Setting auth_method to pkcs15-ldap will - enable ldap based authenticaton. + enable LDAP based authentication. These options are supported: @@ -1045,32 +1054,32 @@ OpenSSL> -H hostname - hostname of ldap server + hostname of LDAP server -P port - port or ldap server + port or LDAP server -S scope - scope of ldap server + scope of LDAP server -b binddn - binddn for ldap connection + binddn for LDAP connection -p passwd - password for ldap bind + password for LDAP bind -B base - base for ldap bind + base for LDAP bind @@ -1080,13 +1089,13 @@ OpenSSL> -f filter - filter in ldap search + filter in LDAP search FIXME: provide an example - of ldap data structure, config + of LDAP data structure, config file etc.
@@ -1094,20 +1103,20 @@ OpenSSL> - The OpenSC PKCS11 library + The OpenSC PKCS #11 library
- What is PKCS11 + What is PKCS #11 - PKCS11 is a standard API for accessing cryptographic tokens + PKCS #11 is a standard API for accessing cryptographic tokens such as smart cards, Hardware Security Modules, ... It contains functions like C_GetSlotList(), C_OpenSession(), C_FindObjects(), C_Login(), C_Decrypt(), ... - Some core concepts of pkcs11 are: + Some core concepts of PKCS #11 are: slot: the place in which a smart card can be put. Usually this @@ -1121,7 +1130,7 @@ OpenSSL> object: a key, a certificate, some data, ... Is either a token object (if it resides on the card) or a session object (if it doesn't reside on the card, e.g. a certificate given to the - pkcs11 library to do a verification). + PKCS #11 library to do a verification). session: before you can do anything with a token, you have to @@ -1147,7 +1156,8 @@ OpenSSL> and the user PIN. However, smart cards can have more than 1 user PIN. A way to this solve problem is to have multiple 'virtual' slots, - as explained in appendix D of the pkcs11 standard. So per physical + as explained in appendix D of the PKCS #11 standard. So per physical reader, you have a number of virtual slots. If you insert a card in the reader, a token will appear in all the virtual slots, and each token will contain 1 PIN along with the private keys @@ -1162,7 +1172,7 @@ OpenSSL> - Opensc implements the following behaviour: for each PIN, its + OpenSC implements the following behaviour: for each PIN, its private keys and corresponding certs, there is 1 virtual slot allocated. If there are any objects left, they are put in the next free virtual slot. And if there are some virtual slots left, @@ -1249,7 +1259,8 @@ OpenSSL> Other parts of OpenSC be should ported as well. Also we should implement native Win32 APIs such as CryptoAPI Provider, some login stuff and - ActiveX plugin for Explorer to do the signing. + ActiveX plugin for Internet Explorer to do the + signing.
@@ -1259,9 +1270,10 @@ OpenSSL> Troubleshooting - A mailing-list has been set up for support and + A mailing list has been set up for support and discussion about the OpenSC project. Additional info is - available at OpenSC web site. + available at the + OpenSC web site. @@ -1285,11 +1297,11 @@ OpenSSL> OpenSC Signer is a Netscape plugin that will generate digital signatures using facilities on PKI-capable - smartcards. + smart cards.
- Building and Installing libopensc + Building and installing the OpenSC Signer You should specify your plugin directory with: @@ -1316,10 +1328,10 @@ OpenSSL> - A few hints on docbook documents + A few hints on DocBook documents - This document is maintained as docbook xml + This document is maintained as DocBook XML document. Here are some hints and links for newcomers. @@ -1328,38 +1340,38 @@ OpenSSL> This document is written in XML not SGML. To convert it, use a XSL stylesheet, not an DSSSL stylesheet. Ignore all tools and - webpages talking about SGML or DSSSL, those - talk about legecy technology no longer used + web pages talking about SGML or DSSSL, those + talk about legacy technology no longer used and no longer up to date. - The Docbook - Project at Sourceforge has the - XSL stylshet used to convert this XML document + DocBook + Open Repository project at SourceForge has the + XSL stylesheet used to convert this XML document to other formats. - Docbook, the - definite Guide (O'Reilly Book) documents - Docbook, is very handy as reference and available - Online for free. + DocBook: The + Definitive Guide (O'Reilly Book) documents + DocBook, is very handy as reference and available + online for free. - Online - Book on Docbook, XML and XSL is a book - with a greate introduction on how to create a document, + DocBook + XSL: The Complete Guide is a book + with a great introduction on how to create a document, how to convert it, where to get the software, tools and everything. It you a fast road to editing this document, look at this book. - THis document might be ugly. If you know html, + This document might be ugly. If you know html, please help us to improve it. Some stuff can - be tuned in the xsl stylesheet (see Reference for the HTML stylesheet parameters), but most stuff can be improved via CSS + be tuned in the XSL stylesheet (see Reference for the HTML stylesheet parameters), but most stuff can be improved via CSS styles. We need help on this !