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 @@ - + +
- -- Table of Contents + + Table of Contents +
+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. +
- Table of Contents + + Table of Contents +
+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: +
+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: +
+
-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 + |
- Table of Contents + + Table of Contents +
+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. +
+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: +
+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. ++ + 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. +
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 - < - - 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 - 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 + + + + < + + + 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 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 - < - - opensc-devel@opensc.org>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 - < - - opensc-devel@opensc.org>.
-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 + + + < + + + opensc-devel@opensc.org + > + 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 + + + < + + + opensc-devel@opensc.org + > + . +
+ ++ 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. +
- Table of Contents + + Table of Contents +
+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. +
+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: +
+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. +
+
- -set include=%include%;.....\inc32 -set lib=%lib%;.....\out32dll -set path=%path%;....\out32dll -- |
-
+ + set include=%include%;.....\inc32 + set lib=%lib%;.....\out32dll + set path=%path%;....\out32dll + ++ |
+
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. +
- Table of Contents + + Table of Contents +
+Support signing/decrypting, and - initialization
++ Support signing/decrypting, and initialization +
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. +
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. +
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. +
Supported - need to fill in the details
++ Supported - need to fill in the details +
Supported - need to fill in the details
++ Supported - need to fill in the details +
Supported - need to fill in the details
++ Supported - need to fill in the details +
Supported - need to fill in the details
++ Supported - need to fill in the details +
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. +
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. +
- Table of Contents + + Table of Contents +
+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?
-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
-Examples:
-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? +
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 -
+ +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:
-+ 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:
-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 +
+ ++ Examples: +
+ ++ For Windows, only the PKCS #11 engine (not the OpenSC + engine) has been ported; use "engine_pkcs11" instead of + "engine_pkcs11.so". +
++ 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 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: +
+ ++ Generic options: +
+ +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. +
++ Setting auth_method to pkcs15-ldap will enable LDAP + based authentication. These options are supported: +
+FIXME: provide an example of ldap data structure, - config file etc.
+ ++ FIXME: provide an example of LDAP data structure, + config file etc. +
- Table of Contents + + Table of Contents +
+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: +
+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: +
+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. +
- Table of Contents + + Table of Contents +
+
-* 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 + + |
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. +
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 + . +
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/ + +
- Table of Contents + + Table of Contents +
+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. +
+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. +
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 ! +