<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
	"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">

<chapter xml:id="sharing">
	<title>Sharing PKCS#11 modules</title>

	<section xml:id="sharing-problem">
		<title>Multiple consumers of PKCS#11 in a process</title>

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

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

		<para>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 <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
		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.</para>

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

		<para>It is necessary for the two consumers to coordinate their
		initialization and finalization in some fashion. In
		<literal>p11-kit</literal> we provide this coordination in a
		loosely coupled, backwards compatible, and flexible way.</para>
	</section>

	<section xml:id="sharing-managed">
		<title>Managed modules</title>

		<para><literal>p11-kit</literal> wraps PKCS#11 modules to manage
		them and customize their functionality so that they are able
		to be shared between multiple callers in the same process.</para>

		<para>Each caller that uses the
		<link linkend="p11-kit-modules-load"><function>p11_kit_modules_load()</function></link>
		or <link linkend="p11-kit-module-load"><function>p11_kit_module_load()</function></link>
		function gets independent wrapped PKCS#11 module(s). This is unless a caller
		or module configuration specifies that a module should be used in an
		unmanaged fashion.</para>

		<para>When modules are managed, the following aspects are wrapped and
		coordinated:</para>

		<itemizedlist>
		<listitem>
			<para>Calls to <literal>C_Initialize</literal> and
			<literal>C_Finalize</literal> can be called by multiple
			callers.</para>

			<para>The first time that the managed module
			<literal>C_Initialize</literal> is called, the PKCS#11 module's actual
			<literal>C_Initialize</literal> function is called. Subsequent calls by
			other callers will cause <literal>p11-kit</literal> to increment an
			internal initialization count, rather than calling
			<literal>C_Initialize</literal> again.</para>

			<para>Multiple callers can call the managed
			<literal>C_Initialize</literal> function concurrently from different
			threads and <literal>p11-kit</literal> will guarantee that this managed
			in a thread-safe manner.</para>
		</listitem>
		<listitem>
			<para>When the managed module <literal>C_Finalize</literal> 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 actual <literal>C_Finalize</literal>
			function is called.</para>

			<para>Multiple callers can call the managed <literal>C_Finalize</literal>
			function concurrently from different threads and <literal>p11-kit</literal>
			will guarantee that this managed in a thread-safe manner.</para>
		</listitem>
		<listitem>
			<para>Call to <literal>C_CloseAllSessions</literal> only close the
			sessions that the caller of the managed module has opened. This allows the
			<literal>C_CloseAllSessions</literal> function to be used without closing
			sessions for other callers of the same PKCS#11 module.</para>
		</listitem>
		<listitem>
			<para>Managed modules have ability to log PKCS#11 method calls for debugging
			purposes. See the <link linkend="option-log-calls"><literal>log-calls = yes</literal></link>
			module configuration option.</para>
		</listitem>
		</itemizedlist>
	</section>
</chapter>