summaryrefslogtreecommitdiff
path: root/doc/manual/pkcs11.conf.xml
blob: 16e6cb23f8f0de6fc4a8e54c8dc6ea95edbd368b (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
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
<?xml version='1.0'?>
<!DOCTYPE refentry 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">
]>

<refentry id="pkcs11-conf">

<refentryinfo>
	<title>pkcs11.conf</title>
	<productname>p11-kit</productname>
	<authorgroup>
		<author>
			<contrib>Maintainer</contrib>
			<firstname>Stef</firstname>
			<surname>Walter</surname>
			<email>stef@thewalter.net</email>
		</author>
	</authorgroup>
</refentryinfo>

<refmeta>
	<refentrytitle>pkcs11.conf</refentrytitle>
	<manvolnum>5</manvolnum>
	<refmiscinfo class="manual">System Files</refmiscinfo>
</refmeta>

<refnamediv>
	<refname>pkcs11.conf</refname>
	<refpurpose>Configuration files for PKCS#11 modules</refpurpose>
</refnamediv>

<refsect1 id="pkcs11-conf-description">
	<title>Description</title>
	<para>The <command>pkcs11.conf</command> configuration files are a standard
	way to configure PKCS#11 modules.</para>
</refsect1>

<refsect1 id="config-format">
	<title>File format</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>Each setting in the config file is specified consists of a name and
	a value. The name is a simple string consisting of characters and dashes.
	The name consists of alpha numeric characters, dot, hyphen and
	underscore.</para>

	<para>The value is specified after the name on the same line, separated
	from it by a <literal>:</literal> (colon). White space between the
	name and value is ignored.</para>

	<para>Blank lines are ignored. White space at the beginning or end of
	lines is stripped. Lines that begin with a <literal>#</literal> character
	are ignored as comments. Comments are not recognized when they come after
	a value on a line.</para>

	<para>A fictitious module configuration file might look like:</para>
<programlisting>
module: module.so
# Here is a comment

managed: true
setting.2: A long value with text.
x-custom : text
</programlisting>
</refsect1>

<refsect1 id="config-module">
	<title>Module Configuration</title>

	<para>Each configured PKCS#11 module has its own config file. These files
	can be <link linkend="config-locations">placed in various locations</link>.</para>
	<para>The filename of the configuration file may consist of upper and lowercase letters
	underscore, comma, dash and dots. The first characters needs to be an alphanumeric,
	the filename should end with a <literal>.module</literal> extension.</para>
	<para>Most importantly each config file specifies the path of the PKCS#11 module to
	load. A module config file has the following fields:</para>

	<variablelist>
	<varlistentry>
		<term><option>module:</option></term>
		<listitem>
			<para>The filename of the PKCS#11 module to load.
			This should include an extension like <literal>.so</literal></para>
			<para>If this value is blank, then the module will be ignored.
			This can be used in the user configs to override loading of a module
			specified in the system configuration.</para>

			<para>If this is a relative path, then the module will be loaded
			from the <link linkend="devel-paths-modules">default module directory</link>.</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><option>critical:</option></term>
		<listitem>
			<para>Set to <literal>yes</literal> if the module is critical and
			required to load. If a critical module fails to load or initialize,
			then the loading process for all registered modules will abort and
			return an error code.</para>

			<para>This argument is optional and defaults to <literal>no</literal>.</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><option>enable-in:</option></term>
		<listitem>
			<para>A comma and/or space separated list of names of programs that
			this module should only be loaded in. The module will not be loaded
			for other programs using p11-kit. The base name of the process executable
			should be used here, for example
			<literal>seahorse, ssh</literal>.</para>
			<para>This is not a security feature. The argument is optional. If
			not present, then any process will load the module.</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><option>disable-in:</option></term>
		<listitem>
			<para>A comma and/or space separated list of names of programs that
			this module should not be loaded in. The module will be loaded for any
			other programs using p11-kit. The base name of the process
			executable should be used here, for example
			<literal>firefox, thunderbird-bin</literal>.</para>
			<para>This is not a security feature. The argument is optional. If
			not present, then any process will load the module.</para>
		</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
			returned to a caller of p11-kit, modules with a higher number are sorted
			first. When applications search modules for for certificates, keys and
			trust policy information, this setting will affect what find
			first.</para>
			<para>This argument is optional, and defaults to zero. Modules
			with the same <option>priority</option> option will be sorted
			alphabetically.</para>
		</listitem>
	</varlistentry>
	<varlistentry id="option-remote">
		<term><option>remote:</option></term>
		<listitem>
			<para>Instead of loading the PKCS#11 module locally, run the module
			remotely.</para>
			<para>Specify a command to run, prefixed with <literal>|</literal> a pipe.
			The command must speak the p11-kit remoting protocol on its standard in
			and standard out. For example:</para>
<programlisting>
remote: |ssh user@remote p11-kit remote /path/to/module.so
</programlisting>
			<para>Other forms of remoting will appear in later p11-kit releases.</para>
		</listitem>
	</varlistentry>
	<varlistentry>
		<term><option>trust-policy:</option></term>
		<listitem>
			<para>Set to <literal>yes</literal> to use use this module as a source
			of trust policy information such as certificate anchors and black lists.</para>
		</listitem>
	</varlistentry>
	<varlistentry id="option-log-calls">
		<term>log-calls:</term>
		<listitem>
			<para>Set to <literal>yes</literal> to write a log to stderr of all the
			calls into the module. This is only supported for managed modules.</para>

			<para>This argument is optonal and defaults to <literal>no</literal>.</para>
		</listitem>
	</varlistentry>
	</variablelist>

	<para>Do not specify both <literal>enable-in</literal> and <literal>disable-in</literal>
	for the same module.</para>

	<para>Other fields may be present, but it is recommended that field names
	that are not specified in this document start with a <literal>x-</literal>
	prefix.</para>
</refsect1>

<refsect1 id="config-global">
	<title>Global Configuration</title>

	<para>A global configuration may also be present. This file contains settings
	that are not related to a single PKCS#11 module. The location(s) of the
	global configuration are described below. The global configuration file
	can contain the following fields:</para>

	<variablelist>
	<varlistentry>
		<term><option>user-config:</option></term>
		<listitem><para>This will be equal to one of the following values:
		<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>
	<varlistentry>
		<term>log-calls:</term>
		<listitem>
			<para>Set to <literal>yes</literal> to write a log to stderr of all the
			calls into all configured modules. This is only supported for managed
			modules.</para>

			<para>This argument is optional.</para>
		</listitem>
	</varlistentry>
	</variablelist>

	<para>Other fields may be present, but it is recommended that field names
	that are not specified in this document start with a <literal>x-</literal>
	prefix.</para>
</refsect1>

<refsect1 id="config-locations">
	<title>Configuration Files</title>

	<para>Each configured PKCS#11 module is has its own config file. These
	files are placed in a directory. In addition a global config file exists.
	There is a system configuration consisting of the various module config
	files and a file for global configuration. Optionally each user can provide
	additional configuration or override the system configuration.</para>

	<para>The system global configuration file is usually in
	<literal>&sysdir;/pkcs11.conf</literal> and the user global
	configuration file is in <literal>&userdir;/pkcs11.conf</literal> in the
	user's home directory.</para>

	<para>The module config files are usually located in the
	<literal>&sysdir;/modules</literal> directory, with one configuration
	file per module. In addition the <literal>&userdir;/modules</literal> directory
	can be used for modules installed by the user.</para>

	<para>Note that user configuration files are not loaded from the home
	directory if running inside a setuid or setgid program.</para>

	<para>The default system config file and module directory can be changed
	when building p11-kit. Always
	<link linkend="devel-paths">lookup these paths</link> using
	<literal>pkg-config</literal>.</para>
</refsect1>

<refsect1 id="pkcs11-conf-see-also">
	<title>See also</title>
	<simplelist type="inline">
		<member><citerefentry><refentrytitle>p11-kit</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
	</simplelist>
	<para>Further details available in the p11-kit online documentation at
	<ulink url="http://p11-glue.freedesktop.org/doc/p11-kit/">http://p11-glue.freedesktop.org/doc/p11-kit/</ulink>.
	</para>
</refsect1>

</refentry>