summaryrefslogtreecommitdiff
path: root/doc/manual/p11-kit-sharing.xml
blob: e692e3dc136470334a311e805234fdaee2cb9f35 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
<?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-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>
</chapter>