p11-kit: Managed PKCS#11 module loading

Support a new managed style module loading for PKCS#11 modules. This
allows us to better coordinate between multiple callers of the same
PKCS#11 modules and provide hooks into their behavior.

This meant redoing the public facing API. The old methods are now
deprecated, marked and documented as such.

6 files changed, 134 insertions, 56 deletions

diff --git a/doc/manual/Makefile.am b/doc/manual/Makefile.am
index c10375a..b5b80f1 100644
--- a/doc/manual/Makefile.am
+++ b/doc/manual/Makefile.am
@@ -53,6 +53,7 @@ IGNORE_HFILES= \
 	debug.h \
 	dict.h \
 	mock.h \
+	modules.h \
 	pkcs11.h \
 	pkcs11x.h \
 	private.h \
@@ -70,6 +71,7 @@ HTML_IMAGES=
 # e.g. content_files=running.sgml building.sgml changes-2.0.sgml
 content_files=p11-kit-config.xml p11-kit-sharing.xml \
 	p11-kit-devel.xml \
+	p11-kit-proxy.xml \
 	p11-kit-trust.xml \
 	p11-kit.xml \
 	pkcs11.conf.xml \
diff --git a/doc/manual/p11-kit-docs.xml b/doc/manual/p11-kit-docs.xml
index 0397169..5acfb97 100644
--- a/doc/manual/p11-kit-docs.xml
+++ b/doc/manual/p11-kit-docs.xml
@@ -13,6 +13,7 @@
 
 	<xi:include href="p11-kit-config.xml"/>
 	<xi:include href="p11-kit-sharing.xml"/>
+	<xi:include href="p11-kit-proxy.xml"/>
 	<xi:include href="p11-kit-trust.xml"/>
 
 	<chapter xml:id="tools">
@@ -28,6 +29,7 @@
 		<xi:include href="xml/p11-kit-pin.xml"/>
 		<xi:include href="xml/p11-kit-util.xml"/>
 		<xi:include href="xml/p11-kit-future.xml"/>
+		<xi:include href="xml/p11-kit-deprecated.xml"/>
 
 		<index id="api-index-full">
 			<title>API Index</title>
diff --git a/doc/manual/p11-kit-proxy.xml b/doc/manual/p11-kit-proxy.xml
new file mode 100644
index 0000000..7cc3615
--- /dev/null
+++ b/doc/manual/p11-kit-proxy.xml
@@ -0,0 +1,29 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+]>
+<chapter xml:id="sharing">
+	<title>Proxy Module</title>
+
+	<para>When an application is aware of the fact that coordination
+	is necessary between multiple consumers of a PKCS#11 module, and wants
+	to load standard configured PKCS#11 modules, it can link to
+	<literal>p11-kit</literal> and use the functions there to provide this
+	functionality.</para>
+
+	<para>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,
+	<literal>p11-kit</literal> provides a proxy compatibility
+	module.</para>
+
+	<para>This proxy module acts like a normal PKCS#11 module, but
+	internally loads a preconfigured set of PKCS#11 modules and
+	manages their features as described earlier. Each slot in the configured modules
+	is exposed as a slot of the <literal>p11-kit</literal> 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.</para>
+
+	<para>The <literal>C_GetFunctionList</literal> exported entry point of the
+	proxy module returns a new managed PKCS#11 module each time it is called. These
+	managed instances are released when the proxy module is unloaded.</para>
+</chapter>
diff --git a/doc/manual/p11-kit-sections.txt b/doc/manual/p11-kit-sections.txt
index dc85f2d..84f084d 100644
--- a/doc/manual/p11-kit-sections.txt
+++ b/doc/manual/p11-kit-sections.txt
@@ -52,15 +52,22 @@ p11_kit_pin_file_callback
 
 <SECTION>
 <FILE>p11-kit</FILE>
-p11_kit_initialize_registered
-p11_kit_finalize_registered
-p11_kit_registered_modules
-p11_kit_registered_module_to_name
-p11_kit_registered_name_to_module
-p11_kit_registered_option
-p11_kit_initialize_module
-p11_kit_load_initialize_module
-p11_kit_finalize_module
+P11_KIT_MODULE_CRITICAL
+P11_KIT_MODULE_UNMANAGED
+p11_kit_modules_load_and_initialize
+p11_kit_modules_finalize_and_release
+p11_kit_modules_load
+p11_kit_modules_initialize
+p11_kit_modules_finalize
+p11_kit_modules_release
+p11_kit_module_load
+p11_kit_module_initialize
+p11_kit_module_finalize
+p11_kit_module_release
+p11_kit_module_for_name
+p11_kit_module_get_name
+p11_kit_module_get_flags
+p11_kit_config_option
 </SECTION>
 
 <SECTION>
@@ -104,3 +111,17 @@ p11_kit_iter_get_object
 p11_kit_iter_load_attributes
 p11_kit_iter_free
 </SECTION>
+
+<SECTION>
+<FILE>p11-kit-deprecated</FILE>
+p11_kit_initialize_registered
+p11_kit_finalize_registered
+p11_kit_registered_modules
+p11_kit_registered_module_to_name
+p11_kit_registered_name_to_module
+p11_kit_registered_option
+p11_kit_initialize_module
+p11_kit_load_initialize_module
+p11_kit_finalize_module
+P11_KIT_DEPRECATED_FOR
+</SECTION>
diff --git a/doc/manual/p11-kit-sharing.xml b/doc/manual/p11-kit-sharing.xml
index e692e3d..01b3c8b 100644
--- a/doc/manual/p11-kit-sharing.xml
+++ b/doc/manual/p11-kit-sharing.xml
@@ -42,52 +42,52 @@
 		loosely coupled, backwards compatible, and flexible way.</para>
 	</section>
 
-	<section xml:id="sharing-initialize">
-		<title>Solution: p11-kit</title>
-
-		<para><literal>p11-kit</literal> 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.</para>
-
-		<para>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.</para>
-
-		<para>This is done in a thread-safe manner. These functions can
-		be used on modules that the consumer loads themselves.</para>
-	</section>
-
-	<section xml:id="sharing-module">
-		<title>Solution: proxy module</title>
-
-		<para>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.</para>
-
-		<para>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,
-		<literal>p11-kit</literal> provides a proxy compatibility
-		module.</para>
-
-		<para>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
-		<literal>p11-kit</literal> 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.</para>
-
-		<para>The proxy module bends the PKCS#11 rules slightly. It does
-		not return the <literal>CKR_CRYPTOKI_ALREADY_INITIALIZED</literal>
-		error code as specified in PKCS#11. However this is a small
-		price to pay for this compatibility.</para>
+	<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>
+		</itemizedlist>
 	</section>
 </chapter>
diff --git a/doc/manual/pkcs11.conf.xml b/doc/manual/pkcs11.conf.xml
index 1814377..1051ee1 100644
--- a/doc/manual/pkcs11.conf.xml
+++ b/doc/manual/pkcs11.conf.xml
@@ -128,6 +128,16 @@ x-custom : text
 		</listitem>
 	</varlistentry>
 	<varlistentry>
+		<term><option>managed:</option></term>
+		<listitem>
+			<para>Set to <literal>no</literal> if the module is not to be managed by
+			p11-kit. Making a module unmanaged is not recommended, and will cause
+			problems if multiple callers in a single process share a PKCS#11 module.</para>
+
+			<para>This argument is optonal and defaults to <literal>yes</literal>.</para>
+		</listitem>
+	</varlistentry>
+	<varlistentry>
 		<term><option>priority:</option></term>
 		<listitem>
 			<para>The value should be an integer. When lists of modules are
@@ -172,6 +182,20 @@ x-custom : text
 		<literal>none</literal>, <literal>merge</literal>,
 		<literal>only</literal>.</para></listitem>
 	</varlistentry>
+	<varlistentry>
+		<term><option>managed:</option></term>
+		<listitem>
+			<para>Set to <literal>yes</literal> or <literal>no</literal> to
+			force all modules to be managed or unmanaged by p11-kit. Setting this
+			setting in a global configuration file will override the
+			<literal>managed</literal> setting in the individual module configuration
+			files. Making modules unmanaged is not recommended, and will cause
+			problems if multiple callers in a single process share a PKCS#11
+			module.</para>
+
+			<para>This argument is optonal.</para>
+		</listitem>
+	</varlistentry>
 	</variablelist>
 
 	<para>Other fields may be present, but it is recommended that field names