From a0ef9771b882bf2dc5bd56fcc6bcfdf47ed90feb Mon Sep 17 00:00:00 2001 From: Stef Walter Date: Thu, 31 Mar 2011 14:50:25 +0200 Subject: Mix in other documentation. --- doc/Makefile.am | 2 +- doc/p11-kit-config.xml | 10 +++-- doc/p11-kit-docs.sgml | 12 ++++-- doc/p11-kit-multiple-problem.xml | 92 ---------------------------------------- doc/p11-kit-sharing.xml | 92 ++++++++++++++++++++++++++++++++++++++++ doc/style.css | 17 +++++--- 6 files changed, 117 insertions(+), 108 deletions(-) delete mode 100644 doc/p11-kit-multiple-problem.xml create mode 100644 doc/p11-kit-sharing.xml (limited to 'doc') diff --git a/doc/Makefile.am b/doc/Makefile.am index b18d86a..fe65836 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -50,7 +50,7 @@ HTML_IMAGES= # Extra SGML files that are included by $(DOC_MAIN_SGML_FILE). # e.g. content_files=running.sgml building.sgml changes-2.0.sgml -content_files=p11-kit-config.xml p11-kit-multiple-problem.xml +content_files=p11-kit-config.xml p11-kit-sharing.xml # SGML files where gtk-doc abbrevations (#GtkWidget) are expanded # These files must be listed here *and* in content_files diff --git a/doc/p11-kit-config.xml b/doc/p11-kit-config.xml index 851f5dc..2284265 100644 --- a/doc/p11-kit-config.xml +++ b/doc/p11-kit-config.xml @@ -35,7 +35,7 @@ underscore. The value is specified after the name on the same line, separated - from it by a a : colon. White space between the + from it by a : (colon). White space between the name and value is ignored. Blank lines are ignored. White space at the beginning or end of @@ -50,8 +50,7 @@ # Here is a comment setting.2: A long value with text. - x-custom : text - + x-custom : text @@ -113,7 +112,10 @@ user's home directory. - The module config files are located XXX> + The module config files are located in the + /etc/pkcs11/modules directory, with one configuration + file per module. In addition the ~/.pkcs11/modules + directory can be used for modules installed by the user. diff --git a/doc/p11-kit-docs.sgml b/doc/p11-kit-docs.sgml index d00cc36..6a5f467 100644 --- a/doc/p11-kit-docs.sgml +++ b/doc/p11-kit-docs.sgml @@ -11,14 +11,18 @@ for p11-kit &version; + + + Reference - - API Index - - + + + API Index + + diff --git a/doc/p11-kit-multiple-problem.xml b/doc/p11-kit-multiple-problem.xml deleted file mode 100644 index a1c19a7..0000000 --- a/doc/p11-kit-multiple-problem.xml +++ /dev/null @@ -1,92 +0,0 @@ - - - - Sharing PKCS#11 modules - -
- Multiple consumers of PKCS#11 in a process - - As more and more applications and libraries use PKCS#11 we run - into a very basic problem. The PKCS#11 modules cannot be initialized and - finalized properly without coordination between the various consumers. - - - An example: An application might use GnuTLS for - TLS connections, and use libgcr for display of certificates. Both of - these want to load (and initialze) the same PKCS#11 modules. There are - many places where this situation occurs, including large applications - like Evolution which due to their dependencies end up using both NSS and - GnuTLS. - - Consumer A loads a PKCS#11 module and uses the module's - C_Initialize function to initialize it, which works as expected. - When consumer B initializes the module (also using C_Initialize), - the error code CKR_CRYPTOKI_ALREADY_INITIALIZED - is correctly returned. This is normal PKCS#11 specification - defined behavior for when a module is initalized twice in the - same process. If consumer B is aware of this situation they may - choose to ignore this error code. - - However when the consumer A is done with its use of the - PKCS#11 module it finalizes the module using the module's - C_Finalize function. This is expected of a well behaved PKCS#11 - consumer. This then causes errors and/or crashes for consumer B, - which cannot know that the module has now been finalized out - from underneath it. - - It is necessary for the two consumers to coordinate their - initialization and finalization in some fashion. In - p11-kit we provide this coordination in a - loosely coupled, backwards compatible, and flexible way. -
- -
- Solution: p11-kit - - p11-kit provides functions to - coordinate initialization and finalization of any PKCS#11 - module. A module may be initialized any number of times using - the p11_kit_initialize_module() function. The first time that - p11_kit_initialize_module() is called for a module, that module's - C_Initialize function is used. Later invocations for the same - module cause p11-kit to increment an internal initialization - count, rather than calling C_Initialize again. - - The p11_kit_finalize_module() is used to finalize a module. - Each time it is called it decrements the internal initialization - count for that module. When the internal initialization count - reaches zero, the module's C_Finalize function is called. - - This is done in a thread-safe manner. These functions can - be used on modules that the consumer loads themselves. -
- -
- Solution: proxy module - - When an application is aware of the fact that coordination - is necessary between multiple consumers of a PKCS#11 module, it - can link to p11-kit and use the functions there to provide - this coordination. - - However most current consumers of PKCS#11 are ignorant of - this problem, and do not link to p11-kit. In order to solve this - multiple initialization problem for all applications, - p11-kit provides a proxy compatibility - module. - - This proxy module acts like a normal PKCS#11 module, but - internally loads a preconfigured set of PKCS#11 modules and - coordinates their initialization and finalization. Each slot - in the configured modules is exposed as a slot of the - p11-kit proxy module. The proxy module is - then used as a normal PKCS#11 module would be. It can be loaded by - crypto libraries like NSS and behaves as expected. - - The proxy module bends the PKCS#11 rules slightly. It does - not return the CKR_CRYPTOKI_ALREADY_INITIALIZED - error code as specified in PKCS#11. However this is a small - price to pay for this compatibility. -
- diff --git a/doc/p11-kit-sharing.xml b/doc/p11-kit-sharing.xml new file mode 100644 index 0000000..a1c19a7 --- /dev/null +++ b/doc/p11-kit-sharing.xml @@ -0,0 +1,92 @@ + + + + Sharing PKCS#11 modules + +
+ Multiple consumers of PKCS#11 in a process + + As more and more applications and libraries use PKCS#11 we run + into a very basic problem. The PKCS#11 modules cannot be initialized and + finalized properly without coordination between the various consumers. + + + An example: An application might use GnuTLS for + TLS connections, and use libgcr for display of certificates. Both of + these want to load (and initialze) the same PKCS#11 modules. There are + many places where this situation occurs, including large applications + like Evolution which due to their dependencies end up using both NSS and + GnuTLS. + + Consumer A loads a PKCS#11 module and uses the module's + C_Initialize function to initialize it, which works as expected. + When consumer B initializes the module (also using C_Initialize), + the error code CKR_CRYPTOKI_ALREADY_INITIALIZED + is correctly returned. This is normal PKCS#11 specification + defined behavior for when a module is initalized twice in the + same process. If consumer B is aware of this situation they may + choose to ignore this error code. + + However when the consumer A is done with its use of the + PKCS#11 module it finalizes the module using the module's + C_Finalize function. This is expected of a well behaved PKCS#11 + consumer. This then causes errors and/or crashes for consumer B, + which cannot know that the module has now been finalized out + from underneath it. + + It is necessary for the two consumers to coordinate their + initialization and finalization in some fashion. In + p11-kit we provide this coordination in a + loosely coupled, backwards compatible, and flexible way. +
+ +
+ Solution: p11-kit + + p11-kit provides functions to + coordinate initialization and finalization of any PKCS#11 + module. A module may be initialized any number of times using + the p11_kit_initialize_module() function. The first time that + p11_kit_initialize_module() is called for a module, that module's + C_Initialize function is used. Later invocations for the same + module cause p11-kit to increment an internal initialization + count, rather than calling C_Initialize again. + + The p11_kit_finalize_module() is used to finalize a module. + Each time it is called it decrements the internal initialization + count for that module. When the internal initialization count + reaches zero, the module's C_Finalize function is called. + + This is done in a thread-safe manner. These functions can + be used on modules that the consumer loads themselves. +
+ +
+ Solution: proxy module + + When an application is aware of the fact that coordination + is necessary between multiple consumers of a PKCS#11 module, it + can link to p11-kit and use the functions there to provide + this coordination. + + However most current consumers of PKCS#11 are ignorant of + this problem, and do not link to p11-kit. In order to solve this + multiple initialization problem for all applications, + p11-kit provides a proxy compatibility + module. + + This proxy module acts like a normal PKCS#11 module, but + internally loads a preconfigured set of PKCS#11 modules and + coordinates their initialization and finalization. Each slot + in the configured modules is exposed as a slot of the + p11-kit proxy module. The proxy module is + then used as a normal PKCS#11 module would be. It can be loaded by + crypto libraries like NSS and behaves as expected. + + The proxy module bends the PKCS#11 rules slightly. It does + not return the CKR_CRYPTOKI_ALREADY_INITIALIZED + error code as specified in PKCS#11. However this is a small + price to pay for this compatibility. +
+ diff --git a/doc/style.css b/doc/style.css index 8015165..67ffff3 100644 --- a/doc/style.css +++ b/doc/style.css @@ -40,22 +40,25 @@ DIV.book, DIV.refentry, DIV.chapter, DIV.index, -DIV.footer { +DIV.footer, +DIV.section { font-family: Verdana, Arial, 'Bitstream Vera Sans', Helvetica, sans-serif; font-size: 9.5pt; line-height: 150%; - margin-right: 1em; } -DIV.book, -DIV.footer { +BODY > DIV.book, +BODY > DIV.footer { margin-left: 1em; + margin-right: 1em; } -DIV.refentry, -DIV.chapter, -DIV.index { +BODY > DIV.refentry, +BODY > DIV.chapter, +BODY > DIV.index, +BODY > DIV.section { margin-left: 3em; + margin-right: 1em; } DIV.variablelist TABLE { -- cgit v1.1