blob: ec17b1ba86bd4d35e78d1bab4f375c2377777288 (
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
94
95
96
97
98
|
<?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"
[
<!ENTITY sysdir SYSTEM "sysdir.xml">
<!ENTITY userdir SYSTEM "userdir.xml">
]>
<chapter xml:id="config">
<title>PKCS#11 Configuration</title>
<section id="config-introduction">
<title>Consistent configuration</title>
<para>In order for multiple applications on the user's desktop to use
PKCS#11 modules in a consistent manner, there must be a configuration
or registry to specify which modules to load and how to use them. The
PKCS#11 specification does not specify such a configuration standard.
</para>
<para>Because of the multi-library module initialization problem, use of
PKCS#11 modules must be coordinated within an application. p11-kit
provides that coordination. Since coordination is required, it follows
that p11-kit can also implement a consistent module configuration.
</para>
</section>
<section id="config-example">
<title>Example</title>
<para>The following sections describe the config format in detail. But first
an example which shows the various features. The configuration below, loads
two modules called 'my-module' and 'nss'. The user settings override some
aspects of the system settings.</para>
<para>Global configuration file: <literal>&sysdir;/pkcs11.conf</literal></para>
<programlisting>
# This setting controls whether to load user configuration from the
# &userdir; directory. Possible values:
# none: No user configuration
# merge: Merge the user config over the system configuration (default)
# only: Only user configuration, ignore system configuration
user-config: merge
</programlisting>
<para>One module configuration file per module: <literal>&sysdir;/modules/my-module</literal></para>
<programlisting>
# This setting controls the actual module library to load. This config file
# might be installed by the package that installs this module library. This
# is not an absolute path name. Relative path names are loaded from the
# $(libdir)/pkcs11 directory by default.
module: my-pkcs11-module.so
# This controls whether the module is required to successfully initialize. If 'yes', then
# a failure to load or initialize this module will result in a p11-kit system failure.
critical: no
</programlisting>
<para>User configuration file: <literal>&userdir;/pkcs11.conf</literal></para>
<programlisting>
# This is an empty file. Files that do not exist are treated as empty.
</programlisting>
<para>User configuration file: <literal>&userdir;/modules/my-module</literal></para>
<programlisting>
# Merge with the settings in the system my-module config file. In this case
# a developer has overridden to load a different module for my-module instead.
module: /home/user/src/custom-module/my-module.so
</programlisting>
<para>User configuration file: <literal>&userdir;/modules/nss</literal></para>
<programlisting>
# Load the NSS libsoftokn.so.3 PKCS#11 library as a module. Note that we pass
# some custom non-standard initialization arguments, as NSS expects.
module: /usr/lib/libsoftokn3.so
x-init-reserved: configdir='sql:/home/test/.pki/nssdb' certPrefix='' keyPrefix='' secmod='socmod.db'
critical: yes
</programlisting>
</section>
<section>
<title>Configuration Files</title>
<para>A complete configuration consists of several files. These files are
text files. Since <literal>p11-kit</literal> is built to be used in all
sorts of environments and at very low levels of the software stack, we
cannot make use of high level configuration APIs that you may find on a
modern desktop.</para>
<para><link linkend="pkcs11.conf">See the manual page</link> for more details
on the format and available options.</para>
<para>Note that user configuration files are not loaded from the home
directory if running inside a setuid or setgid program.</para>
</section>
</chapter>
|
