From c1261a6c2e3d2db1dee4a79fba30bc38b6c78669 Mon Sep 17 00:00:00 2001 From: aj Date: Wed, 25 Jun 2003 20:20:32 +0000 Subject: [PATCH] xml/html based documentation. This can replace: README README.Win32 README.cards README.signer THANKS TODO AUTHORS src/openssh/README src/pkcs11/README src/pam/README src/sslengines/README git-svn-id: https://www.opensc-project.org/svnp/opensc/trunk@1225 c6295689-39f2-0310-b995-f0e70906c6a9 --- docs/Makefile.am | 7 +- docs/opensc.css | 23 ++ docs/opensc.html | 453 +++++++++++++++++++++++ docs/opensc.xml | 944 +++++++++++++++++++++++++++++++++++++++++++++++ docs/opensc.xsl | 11 + 5 files changed, 1435 insertions(+), 3 deletions(-) create mode 100644 docs/opensc.css create mode 100644 docs/opensc.html create mode 100644 docs/opensc.xml create mode 100644 docs/opensc.xsl diff --git a/docs/Makefile.am b/docs/Makefile.am index c36fa728..ef8efdea 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -1,7 +1,8 @@ # Process this file with automake to create Makefile.in XSLTPROC := @XSLTPROC@ -HTMLFILES := usbtoken.html +HTMLFILES := usbtoken.html opensc.html opensc.css +XMLFILES := usbtoken.xml opensc.xml opensc.xsl MAINTAINERCLEANFILES = Makefile.in pkcs15-profile.5 @@ -30,9 +31,9 @@ MANSRC = pkcs15-crypt.1 \ man_MANS = $(MANSRC) pkcs15-profile.5 noinst_DATA = $(HTMLFILES) EXTRA_DIST = $(MANSRC) pkcs15-profile.5.in pkcs-15v1_1.asn \ - usbtoken.xml $(HTMLFILES) doxygen.conf pkcs11.txt + $(XMLFILES) $(HTMLFILES) doxygen.conf pkcs11.txt -STYLESHEET=/usr/share/sgml/docbook/stylesheet/xsl/nwalsh/xhtml/docbook.xsl +STYLESHEET=opensc.xsl %.html: %.xml if HAVE_DOCBOOK diff --git a/docs/opensc.css b/docs/opensc.css new file mode 100644 index 00000000..f902b082 --- /dev/null +++ b/docs/opensc.css @@ -0,0 +1,23 @@ +.screen { + background-color: #dddddd; + cellspacing:"1"; + cellpadding:"1"; +} + +.prompt { + background-color: #dddddd; +} + +.command { + background-color: #dddddd; +} + +.title { +} + +.toc { +} + +.book { + width: 630pt +} diff --git a/docs/opensc.html b/docs/opensc.html new file mode 100644 index 00000000..a52979ff --- /dev/null +++ b/docs/opensc.html @@ -0,0 +1,453 @@ + + +OpenSC Manual

OpenSC Manual

Table of Contents

1. Introduction
2. Authors and Contributors
Thanks
3. Copyright and License
4. Building and Installing libopensc
Windows
Windows with OpenSSL
5. Status
Card Status
Windows
PKCS#11 Module in Netscape and Mozilla
6. Using OpenSC
OpenSC and Netscape
OpenSC and Mozilla
OpenSC and OpenSSL
OpenSC and OpenSSH
Pluggable Authentication Module
eid based authentication
ldap based authentication
7. What needs to be done
Windows
8. Troubleshooting
9. Resources
10. Signer
Building and Installing libopensc
11. A few hints on docbook documents

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. +

Chapter 2. Authors and Contributors

Table of Contents

Thanks

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

Thanks

+ 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: +

Chapter 3. Copyright and License

+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 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
+

Chapter 4. Building and Installing libopensc

Table of Contents

Windows
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. +

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: +

  1. + Copy opensc.conf to your Windows + directory (usually C:\WINDOWS or + C:\WINNT). This is optional. +
  2. + Copy opensc.dll and opensc-pkcs11.dll + to your path. +
  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. +

Windows with OpenSSL

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

  1. + download and compile the openssl + sources from http://www.openssl.org/source/
  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. + 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. + In src/libopensc/Makefile.mak add + libeay32.lib (and gdi32.lib) to the + "link" line +
  5. + In src/pkcs11/Makefile.mak add + libeay32.lib (and gdi32.lib) to the + "link" line +
  6. + 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. +

Chapter 5. Status

Table of Contents

Card Status
Windows
PKCS#11 Module in Netscape and Mozilla

Card Status

CryptoFlex

+ Support signing/decrypting, and initialization +

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. +

Aladdin eToken PRO

+ Support signing/decrypting, and initialization. +

+ NOTE: The eToken does not support keys that can + be used for decryption and signing + simultaneously. You need to create two keys + with different usage. +

Micardo

+ Supported - need to fill in the details +

Miocos

+ Supported - need to fill in the details +

Setcos

+ Supported - need to fill in the details +

Tcos

+ Supported - need to fill in the details +

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. +

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. +

Chapter 6. Using OpenSC

Table of Contents

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

OpenSC and Netscape

  1. + Select menu: Communicator -> Tools -> Security Info +
  2. + Select Cryptographic Modules +
  3. + Click: Add +
  4. + 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. + Select menu: Edit -> Preferences +
  3. + Select category: Privacy & Security -> + Certificates +
  4. + Click: Manage Security Devices +
  5. + Click: Load +
  6. + Fill in module name: "OpenSC PKCS#11 Module" + and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so +

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 how to load the engine and + create a new certificate. + 

+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> 
+

+

+ For Windows use "engine_opensc" instead of "engine_opensc.so". +

+ A typical OpenSSL command might be + req -engine pkcs11 -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 + with an optional prefix of the slot to use. + Slots are counted starting with 0. + "45" would be key 0x45 in the first slot, + S2-46 would be key 0x56 in the third slot. +

+ Actualy 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 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. +

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 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.

+

+ Generic options: +

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

+

eid based authentication

+ This is the default authentication + method. Create a directory + .eid in your home + directory and copy your PEM encoded + certificat 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 authenticaton. + These options are supported: +

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

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

Chapter 7. What needs to be done

Table of Contents

Windows
+* Debian packaging
+* GUI applications
+* Ports to MacOS X (jey) and Win32 (fabled?)
+* 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
+

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. +

Chapter 8. Troubleshooting

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

Chapter 9. Resources

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

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

Chapter 10. Signer

Table of Contents

Building and Installing libopensc

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

Building and Installing libopensc

+ 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 11. 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 + Project at Sourceforge has the + XSL stylshet 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. +

+ Online + Book on Docbook, XML and XSL is 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 ! +

diff --git a/docs/opensc.xml b/docs/opensc.xml new file mode 100644 index 00000000..3d9dca2a --- /dev/null +++ b/docs/opensc.xml @@ -0,0 +1,944 @@ + + + OpenSC Manual + + + OpenSC Development Team + opensc-devel@opensc.org + + + + + + + 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. + + + + + Authors and Contributors + + + Here is a list of all Authors and Contributors + of OpenSC in alphabetical order: + + + + + Robert Bihlmeyer robbe@orcus.priv.at + + + + Stef Hoeben Hoeben.S@Zetes.com + + + + Andreas Jellinghaus aj@dungeon.inka.de> + + + + Olaf Kirch okir@suse.de + + + + Kevin Stefanik kstef@mtppi.org + + + + Antti Tapaninen aet@cc.hut.fi + + + + Timo Teräs timo.teras@iki.fi + + + + Juha Yrjölä juha.yrjola@iki.fi + + + +
+ Thanks + + + The following people provided inspiration, + moral support and/or valuable information + during the development of OpenSC: + + + + + Antti Partanen + antti.partanen@vrk.intermin.fi + + + + David Corcoran corcoran@linuxnet.com + + + + + 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: + + + + + Matthias Brüstle + + + + Markus Friedl + + + + Geoff Thrope geoff@geoffthorpe.net + + +
+ + + + Copyright and License + + +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 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 + + + + + Building and Installing libopensc + + + 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 + + + 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: + + + + + Copy opensc.conf to your Windows + directory (usually C:\WINDOWS or + C:\WINNT). This is optional. + + + + Copy opensc.dll and opensc-pkcs11.dll + to your path. + + + + 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 + + + This adds extended functionality. E.g. the + pkcs15-init tool, pkcs11 hash mechanisms and + more pkcs11 signature mechs. + + + + + download and compile the openssl + sources from + + + + 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 + + + + + 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 + + + + In src/libopensc/Makefile.mak add + libeay32.lib (and gdi32.lib) to the + "link" line + + + + In src/pkcs11/Makefile.mak add + libeay32.lib (and gdi32.lib) to the + "link" line + + + + 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. + + +
+ + + + + Status + + +
+ Card Status + + + + + + CryptoFlex + + + + + Support signing/decrypting, and initialization + + + + 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. + + + + Aladdin eToken PRO + + + + Support signing/decrypting, and initialization. + + + + NOTE: The eToken does not support keys that can + be used for decryption and signing + simultaneously. You need to create two keys + with different usage. + + + + Micardo + + + + Supported - need to fill in the details + + + + Miocos + + + + Supported - need to fill in the details + + + + Setcos + + + + Supported - need to fill in the details + + + + Tcos + + + + Supported - need to fill in the details + + + +
+ +
+ 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. + +
+ +
+ 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. + +
+ + + + Using OpenSC + +
+ OpenSC and Netscape + + + + Select menu: Communicator -> Tools -> Security Info + + + + Select Cryptographic Modules + + + + Click: Add + + + + 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 + + + + Make sure Personal Security Manager (PSM) is + installed (eg. mozilla-psm package is + installed). + + + + Select menu: Edit -> Preferences + + + + Select category: Privacy & Security -> + Certificates + + + + Click: Manage Security Devices + + + + Click: Load + + + + Fill in module name: "OpenSC PKCS#11 Module" + and module file: /path/to/opensc/lib/pkcs11/opensc-pkcs11.so + + +
+ +
+ 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 how to load the engine and + create a new certificate. + +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> + + + + + For Windows use "engine_opensc" instead of "engine_opensc.so". + + + + A typical OpenSSL command might be + req -engine pkcs11 -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 + with an optional prefix of the slot to use. + Slots are counted starting with 0. + "45" would be key 0x45 in the first slot, + S2-46 would be key 0x56 in the third slot. + + + + Actualy 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 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. + + +
+ +
+ 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 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. + + + + + + Generic options: + + + -h + Show help + + + + -r reader + Reader name (FIXME: not number?) + + + + +
+ eid based authentication + + + This is the default authentication + method. Create a directory + .eid in your home + directory and copy your PEM encoded + certificat 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 authenticaton. + These options are supported: + + + + + -L ldap.conf + Configuration file to load + + + + -A entry + Add new entry + + + + -E entry + Set current entry + + + + -H hostname + hostname of ldap server + + + + -P port + port or ldap server + + + + -S scope + scope of ldap server + + + + -b binddn + binddn for ldap connection + + + + -p passwd + password for ldap bind + + + + -B base + base for ldap bind + + + + -a attributes + attributes to fetch + + + + -f filter + filter in ldap search + + + + + FIXME: provide an example + of ldap data structure, config + file etc. + +
+
+ + + + What needs to be done + + +* Debian packaging +* GUI applications +* Ports to MacOS X (jey) and Win32 (fabled?) +* 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 + + +
+ 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. + +
+ + + + + Troubleshooting + + + A mailing-list has been set up for support and + discussion about the OpenSC project. Additional info is + available at OpenSC web site. + + + + + Resources + + + See the OpenSC web site at + + + + + Information about Assuan and project Ägypten: + + + + + + Signer + + + OpenSC Signer is a Netscape plugin that will generate + digital signatures using facilities on PKI-capable + smartcards. + + +
+ Building and Installing libopensc + + + 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. + +
+ + + + 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 + Project at Sourceforge has the + XSL stylshet 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. + + + + Online + Book on Docbook, XML and XSL is 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 ! + + + diff --git a/docs/opensc.xsl b/docs/opensc.xsl new file mode 100644 index 00000000..dca69a98 --- /dev/null +++ b/docs/opensc.xsl @@ -0,0 +1,11 @@ + + + + + + + + + + +