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
|
<chapter id="xmlsec-notes-compiling">
<title>Building the application with XML Security Library.</title>
<sect1 id="xmlsec-notes-compiling-overview">
<title>Overview.</title>
<para>Compiling and linking application with XML Security
Library requires specifying correct compilation flags, library files
and paths to include and library files. As we discussed before,
XML Security Library consist of the core xmlsec library and several
xmlsec-crypto libraries. Application has a choice of selecting crypto
library at link time or dynamicaly loading it at run time. Please note,
that loading crypto engines dynamicaly may introduce security problems
on some platforms.
</para>
</sect1>
<sect1 id="xmlsec-notes-include-files" >
<title>Include files.</title>
<para>In order to use XML Security Library an application should include
one or more of the following files:
<itemizedlist>
<listitem>
<para><link linkend="XMLSEC-XMLSEC">xmlsec/xmlsec.h</link> -
XML Security Library initialization and shutdown functions;
</para>
</listitem>
<listitem>
<para><link linkend="XMLSEC-XMLDSIG">xmlsec/xmldsig.h</link> -
XML Digital Signature functions;</para>
</listitem>
<listitem>
<para><link linkend="XMLSEC-XMLENC">xmlsec/xmlenc.h</link> -
XML Encryption functions;</para>
</listitem>
<listitem>
<para><link linkend="XMLSEC-XMLTREE">xmlsec/xmltree.h</link> -
helper functions for XML documents manipulation;
</para>
</listitem>
<listitem>
<para><link linkend="XMLSEC-TEMPLATES">xmlsec/templates.h</link> -
helper functions for dynamic XML Digital Signature and
XML Encryption templates creation;
</para>
</listitem>
<listitem>
<para><link linkend="XMLSEC-CRYPTO">xmlsec/crypto.h</link> -
automatic XML Security Crypto Library selection.
</para>
</listitem>
</itemizedlist>
</para>
<para>If necessary, the application should also include LibXML,
LibXSLT and crypto library header files.
</para>
<para>
<example>
<title>Example includes file section.</title>
<programlisting><![CDATA[
#include <libxml/tree.h>
#include <libxml/xmlmemory.h>
#include <libxml/parser.h>
#ifndef XMLSEC_NO_XSLT
#include <libxslt/xslt.h>
#endif /* XMLSEC_NO_XSLT */
#include <xmlsec/xmlsec.h>
#include <xmlsec/xmltree.h>
#include <xmlsec/xmldsig.h>
#include <xmlsec/xmlenc.h>
#include <xmlsec/templates.h>
#include <xmlsec/crypto.h>
]]></programlisting>
</example>
</para>
</sect1>
<sect1 id="xmlsec-notes-compiling-unix" >
<title>Compiling and linking on Unix.</title>
<para>There are several ways to get necessary compilation
and linking information on Unix and application can use
any of these methods to do crypto engine selection either
at linking or run time.
<itemizedlist>
<listitem><para>PKG_CHECK_MODULES() macro
<example>
<title>Using PKG_CHECK_MODULES() macro in a configure.in file
to select crypto engine (openssl) at linking time.</title>
<programlisting><![CDATA[
dnl
dnl Check for xmlsec and friends
dnl
PKG_CHECK_MODULES(XMLSEC, xmlsec1-openssl >= 1.0.0 xml2 libxslt,,exit)
CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
]]></programlisting>
</example>
<example>
<title>Using PKG_CHECK_MODULES() macro in a configure.in file
to enable dynamical loading of xmlsec-crypto library.</title>
<programlisting><![CDATA[
dnl
dnl Check for xmlsec and friends
dnl
PKG_CHECK_MODULES(XMLSEC, xmlsec1 >= 1.0.0 xml2 libxslt,,exit)
CFLAGS="$CFLAGS $XMLSEC_CFLAGS"
CPPFLAGS="$CPPFLAGS $XMLSEC_CFLAGS"
LDFLAGS="$LDFLAGS $XMLSEC_LIBS"
]]></programlisting>
</example>
</para></listitem>
<listitem><para>pkg-config script
<example>
<title>Using pkg-config script in a Makefile
to select crypto engine (nss) at linking time.</title>
<programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c
CFLAGS += -g $(shell pkg-config --cflags xmlsec1-nss)
LDFLAGS += -g
LIBS += $(shell pkg-config --libs xmlsec1-nss)
all: $(PROGRAM)
%: %.c
$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
clean:
@rm -rf $(PROGRAM)
]]></programlisting>
</example>
<example>
<title>Using pkg-config script in a Makefile
to enable dynamical loading of xmlsec-crypto library.</title>
<programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c
CFLAGS += -g $(shell pkg-config --cflags xmlsec1)
LDFLAGS += -g
LIBS += $(shell pkg-config --libs xmlsec1)
all: $(PROGRAM)
%: %.c
$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
clean:
@rm -rf $(PROGRAM)
]]></programlisting>
</example>
</para></listitem>
<listitem><para>xmlsec1-config script
<example>
<title>Using xmlsec1-config script in a Makefile
to select crypto engine (e.g. gnutls) at linking time.</title>
<programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c
CFLAGS += -g $(shell xmlsec1-config --crypto gnutls --cflags)
LDFLAGS += -g
LIBS += $(shell xmlsec1-config --crypto gnutls --libs)
all: $(PROGRAM)
%: %.c
$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
clean:
@rm -rf $(PROGRAM)
]]></programlisting>
</example>
<example>
<title>Using xmlsec1-config script in a Makefile
to enable dynamical loading of xmlsec-crypto library.</title>
<programlisting><![CDATA[
PROGRAM = test
PROGRAM_FILES = test.c
CFLAGS += -g $(shell xmlsec1-config --cflags)
LDFLAGS += -g
LIBS += $(shell xmlsec1-config --libs)
all: $(PROGRAM)
%: %.c
$(cc) $(PROGRAM_FILES) $(CFLAGS) $(LDFLAGS) -o $(PROGRAM) $(LIBS)
clean:
@rm -rf $(PROGRAM)
]]></programlisting>
</example>
</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="xmlsec-notes-compiling-windows" >
<title>Compiling and linking on Windows.</title>
<para>On Windows there is no such simple and elegant solution.
Please check <filename>README</filename> file in <filename>win32</filename>
folder of the library package for latest instructions.
However, there are few general things, that you need to remember:
<itemizedlist>
<listitem><para>
<emphasis>All libraries linked to your application must be compiled
with the same Microsoft Runtime Libraries.</emphasis>
</para></listitem>
<listitem><para>
<emphasis>Static linking with XML Security Library requires
additional global defines:</emphasis>
<informalexample><programlisting>
#define LIBXML_STATIC
#define LIBXSLT_STATIC
#define XMLSEC_STATIC
</programlisting></informalexample>
</para></listitem>
<listitem><para>
If you do not want to dynamicaly load xmlsec-crypto library
and prefer to select crypto engine at linking then you should
link your application with xmlsec and at least one of
xmlsec-crypto libraries.
</para></listitem>
<listitem><para>
In order to enable dynamic loading for xmlsec-crypto library
you should add additional global define:
<informalexample><programlisting>
#define XMLSEC_CRYPTO_DYNAMIC_LOADING
</programlisting></informalexample>
</para></listitem>
</itemizedlist>
</para>
</sect1>
<sect1 id="xmlsec-notes-compiling-others">
<title>Compiling and linking on other systems.</title>
<para>Well, nothing is impossible, it's only software (you managed to
compile the library itself, do you?).
I'll be happy to include in this manual your expirience with
compiling and linking applications with XML Security Library
on other platforms (if you would like to share it).
</para>
</sect1>
</chapter>
|
