summaryrefslogtreecommitdiff
path: root/doc/p11-kit-devel.xml
blob: bbe6c0a434b6ee85590dac98e2da5474c6be71d0 (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
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
<?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="devel">
	<title>Building, Packaging, and Contributing to p11-kit</title>

	<section id="devel-links">
		<title>Helpful Resources</title>

		<para>Use the following to find more information about
		contributing to p11-kit beyond what's in this manual:</para>

		<itemizedlist>
			<listitem><para><ulink url="http://p11-glue.freedesktop.org/p11-kit.html">Website</ulink></para></listitem>
			<listitem><para><ulink url="mail:p11-glue@lists.freedesktop.org">Mailing list</ulink></para></listitem>
			<listitem><para><ulink url="https://bugs.freedesktop.org/enter_bug.cgi?product=p11-glue&amp;component=p11-kit">Bugzilla</ulink></para></listitem>
		</itemizedlist>
	</section>

	<section id="devel-paths">
		<title>Packaging PKCS#11 module configs</title>

		<para>Developers or packagers of PKCS#11 modules need to install various
		files into specific locations so that p11-kit will recognize and load the
		module correctly.</para>

		<para>You should use <literal>pkg-config</literal> as described below
		to determine configuration paths. p11-kit installs a
		<literal>pkg-config</literal> file called <literal>p11-kit-1.pc</literal>.
		This file contains all the information about the various paths that p11-kit
		looks for files at.</para>

		<section id="devel-paths-config">
			<title>Path to place module configuration</title>

			<para>As described in the <link linkend="config-module">module configuration</link>
			documentation, each PKCS#11 module should install a config file describing
			that module. These config files should be installed to a specific directory which
			can be determined by running:</para>

			<programlisting>
$ <command>pkg-config p11-kit-1 --variable p11_module_configs</command>
/usr/share/p11-kit/modules</programlisting>
		</section>

		<section id="devel-paths-modules">
			<title>Default path for modules with relative paths</title>

			<para>If a <link linkend="config-module">module configuration</link>
			contains a relative path in its <literal>module:</literal> setting,
			then that module will be loaded from the default module path. This
			path can be determined by running:</para>

			<programlisting>
$ <command>pkg-config p11-kit-1 --variable p11_module_path</command>
/usr/lib64/pkcs11</programlisting>
		</section>

	</section>

	<section id="devel-commands">
		<title>Customizing installed commands</title>

		<para>The <literal>p11-kit</literal> tool provides a
		<literal>extract-trust</literal> command which extracts trust
		policy information such as certificate anchors and so on
		into files for use with libraries that cannot read this trust
		information directly.</para>

		<para>In order to be useful the <literal>extract-trust</literal>
		command needs to be customized per distribution or site. You can
		find this file in at <literal>tools/p11-kit-trust-extract.in</literal>
		in the p11-kit source code.</para>

		<para>The command is implemented as a simple script which
		performs the various <literal>p11-kit extract</literal> commands
		necessary to extract the information.</para>

		<para>Using this script as a standard way to extract this
		information allows for consistency between distributions and ease
		of system administration.</para>
	</section>

	<section id="devel-building">
		<title>Compiling p11-kit from Source</title>
		<para>This describes how to compiling the p11-kit package from
		source code. This is normally only necessary for those wishing to
		contribute to the project or package p11-kit.</para>

		<para>You can download
		<ulink url="http://p11-glue.freedesktop.org/releases/">tarballs
		of the releases</ulink> of p11-kit or
		<ulink url="http://cgit.freedesktop.org/p11-glue/p11-kit/">check
		out the source code from git</ulink>. This documentation will not
		go into all the details of how to get your development environment
		set up and instead focus on the what's unique to compiling p11-kit.</para>

		<section id="devel-building-unix">
			<title>Building on UNIX</title>
			<para>p11-kit uses the standard GNU build system, using autoconf for package
			configuration and resolving portability issues, automake for building makefiles
			that comply with the GNU Coding Standards, and libtool for building shared
			libraries on multiple platforms. The normal sequence for compiling and
			installing the p11-kit library is thus:</para>

<programlisting>
$ ./configure --prefix=/path/to/prefix ...
$ make
$ make install
</programlisting>

			<para>If you've checked out the source code from git, then the
			<command>configure</command> script does not yet exist. So use
			the following instead:</para>

<programlisting>
$ ./autogen.sh --prefix=/path/to/prefix ...
$ make
$ make install
</programlisting>

			<para>The standard options provided by GNU autoconf may be passed to the configure
			script. Please see the autoconf documentation or run <literal>./configure --help</literal>
			for information about the standard options. In particular you probably want to adjust
			the <literal>--prefix=/xxx</literal> argument depending on your system and development
			environment.</para>
		</section>

		<section id="devel-building-dependencies">
			<title>Optional Dependencies</title>

			<para>On a modern GNU Linux system, p11-kit has no required dependencies other
			than the standard C library. However on older UNIX systems, some of the following
			may be required.</para>

			<itemizedlist>
				<listitem><para><command>gettext</command> is required if your system doesn't
				have the <literal>gettext()</literal> functionality for handling message
				translation databases. This can be provided by the libintl library from
				the <ulink url="http://www.gnu.org/software/gettext">GNU gettext
				package</ulink>.</para></listitem>
				<listitem><para><command>pthread</command> is required if your (ancient) system
				doesn't have this included in the base system. How this is provided is platform
				specific.</para></listitem>
			</itemizedlist>

			<para>In addition p11-kit has several optional dependencies. If these are not available
			during the build, then certain features will be disabled.</para>

			<itemizedlist>
				<listitem><para><command>gtk-doc</command> is required to build the reference
				manual. Use <literal>--enable-doc</literal> to control this
				dependency.</para></listitem>
				<listitem><para><command>xsltproc</command> is required to build the command
				manual pages. Use <literal>--enable-doc</literal> to control this
				dependency.</para></listitem>
				<listitem><para><command>libtasn1</command> is required to build the trust
				module and code that interacts with certificates.</para></listitem>
			</itemizedlist>

		</section>

		<section id="devel-building-configure">
			<title>Extra Configuration Options</title>

			<para>In addition to the normal options, the configure script in the p11-kit library
			supports these additional arguments:</para>

			<variablelist>
				<varlistentry>
					<term><option>--disable-trust-module</option></term>
					<listitem><para>Disables building of the trust policy module.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--disable-debug</option>, <option>--enable-debug</option></term>
					<listitem><para>By default p11-kit is built with debug symbols assertions and
					and precondition checks. Enabling the debug option configures even more
					detailed debug build, including disabling optimization. Disabling the debug
					option is not recommended, as it disables all assertions, preconditions and
					internal consistency checks, although it may result it a slightly faster
					library.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--enable-doc</option></term>
					<listitem><para>Enables building of the documentation and command line manual.
					The documentation is built in the <literal>doc/html/</literal> directory of
					the build. Requires the <literal>gtk-doc</literal> and <literal>xsltproc</literal>
					dependencies.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--enable-strict</option></term>
					<listitem><para>Enables strict checks during building of p11-kit. All
					compiler warnings become errors.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--with-libtasn1</option>, <option>--without-libtasn1</option></term>
					<listitem><para>Build with a dependency on the libtasn1 library. This dependency
					allows the trust policy module to be built as well as other code that interacts with
					certificates.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--with-module-path</option></term>
					<listitem><para>Specify the path to look for PKCS#11 modules which were
					listed in a module config file with a relative path.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--with-system-anchors</option></term>
					<listitem><para>Specify the files or directories to look for system
					certificate anchors. Multiple files and/or directories are specified with
					a <literal>:</literal> in between them.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--with-system-certificates</option></term>
					<listitem><para>Specify the files or directories to look for other
					non-anchor system certificates. Multiple files and/or directories are
					specified with a <literal>:</literal> in between them.</para></listitem>
				</varlistentry>
				<varlistentry>
					<term><option>--with-system-config</option></term>
					<listitem><para>Specify the path to look for p11-kit config files. This
					usually defaults to something like <literal>/etc/pkcs11</literal></para></listitem>
				</varlistentry>
			</variablelist>
			<para></para>
		</section>
	</section>

	<section id="devel-building-style">
		<title>Coding Style</title>

		<para>We use a code style similar to the linux kernel. Use tabs
		to indent and spaces to align/wrap beyond the indentation level.</para>

		<para>We don't try to guarantee completely robust and problem free
		behavior in cases where the caller or system isn't behaving. We
		consider these to be outside of our control:</para>

		<itemizedlist>
			<listitem><para>Broken input from callers. We use preconditions
			to check input and immediately return. We don't try to provide
			error codes for all the various ways callers can screw
			around.</para></listitem>

			<listitem>
			<para>Out of memory. It is pretty much impossible to handle out
			of memory errors correctly. Handling them alongside other errors
			is naive and broken. We don't try to guarantee library state
			(such as locks or memory leaks) when memory allocation fails.</para>
			<para>We do check the results from all memory allocations, but
			treat them as unexpected conditions. As a nod to the behavior
			of callers of this library, we don't abort on memory allocation
			failures. We use preconditions with somewhat sane results.</para>
			<para>Exception: when reading files or allocating potentially
			unbounded amounts of memory, we should respond robustly to memory
			allocation failures.</para>
			</listitem>
		</itemizedlist>

		<para>These unexpected conditions indicate a bug either in p11-kit or
		in the system. All bets are off once this occurs.</para>

		<para>Use the <literal>return_val_xxx()</literal> precondition macros to
		check for unexpected conditions.</para>
	</section>

	<section id="devel-testing">
		<title>Testing and Code Coverage</title>

		<para>As a general rule changes to p11-kit should have a tests exercising
		that change. Use the <literal>make check</literal> command to run all
		the tests. If you run it from a subdirectory only the tests in that
		directory will be run.</para>

		<para>Build p11-kit with the <option>--enable-coverage</option> configure
		option to build code coverage support.</para>

		<para>Once you've done that you can either use <literal>make coverage</literal>
		to build code coverage information. Alternatively (and this is usually
		easier) you can use
		<ulink url="http://stef.thewalter.net/2012/12/git-coverage-useful-code-coverage.html">
			<literal>git coverage</literal></ulink> to easily check whether
		you've tested the lines changed by a patch.</para>

		<para>A code coverage report is
			<ulink url="http://p11-glue.freedesktop.org/build/coverage">available online</ulink></para>.
	</section>

	<section id="devel-debugging">
		<title>Debugging Tips</title>

		<para>Unexpected conditions will produce critical warnings by p11-kit.
		These are often failed internal preconditions, and usually indicate a
		bug either in p11-kit or the software calling it.</para>

		<para>You can use the environment variable <literal>P11_KIT_STRICT=yes</literal>
		to make p11-kit do an <literal>abort()</literal> (and core dump depending on
		your configuration) when a critical warning occurs.</para>
	</section>
</chapter>