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
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>XML Security Library: Documentation</title>
<link rel="stylesheet" href="css/main.css">
</head>
<body><table width="100%" valign="top"><tr valign="top">
<td valign="top" align="left" width="210">
<img src="images/logo.gif" alt="XML Security Library" border="0"><p></p>
<ul>
<li><a href="index.html">Home</a></li>
<li><a href="download.html">Download</a></li>
<ul><li><a href="https://github.com/lsh123/xmlsec">GitHub</a></li></ul>
<li><a href="news.html">News</a></li>
<li><a href="documentation.html">Documentation</a></li>
<ul>
<li><a href="faq.html">FAQ</a></li>
<li><a href="api/xmlsec-notes.html">Tutorial</a></li>
<li><a href="api/xmlsec-reference.html">API reference</a></li>
<li><a href="api/xmlsec-examples.html">Examples</a></li>
</ul>
<li><a href="xmldsig.html">XML Digital Signature</a></li>
<li><a href="xmlenc.html">XML Encryption</a></li>
<li><a href="c14n.html">XML Canonicalization</a></li>
<li><a href="bugs.html">Reporting Bugs</a></li>
<li><a href="mailing-list.html">Mailing list</a></li>
<li><a href="related.html">Related</a></li>
<li><a href="authors.html">Authors</a></li>
</ul>
<table width="100%">
<tr>
<td width="15"></td>
<td><a href="http://xmlsoft.org/"><img src="images/libxml2-logo.png" alt="LibXML2" border="0"></a></td>
</tr>
<tr>
<td width="15"></td>
<td><a href="http://xmlsoft.org/XSLT"><img src="images/libxslt-logo.png" alt="LibXSLT" border="0"></a></td>
</tr>
<tr>
<td width="15"></td>
<td><a href="http://www.openssl.org/"><img src="images/openssl-logo.png" alt="OpenSSL" border="0"></a></td>
</tr>
<!--Links - start--><!--Links - end-->
</table>
</td>
<td valign="top"><table width="80%" valign="top" style="margin-left:10px;"><tr><td valign="top" align="left" id="xmlsecContent">
<div align="center">
<h1>Frequently Asked Questions</h1>
</div>
<div>
<h3>0. Where can I read more about XML Signature and XML Encryption?</h3>
<p>First of all, read the original specifications: <a href="http://www.w3.org/Signature/">XML Digital Signature</a> and
<a href="http://www.w3.org/Encryption/">XML Encrytpion</a>. Also there <a href="related.html#books">several books</a>
available that can help you to get started.<br></p>
</div>
<div>
<h3>1. License(s).</h3>
<h4>
<a name="section_1_1"></a>1.1. Licensing Terms for XMLSec library.</h4>
<p>XML Security Library is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a>,
see the file Copyright in the distribution for the precise wording. </p>
<h4>
<a name="section_1_2"></a>1.2. Can I use xmlsec with proprietary application or library? Can I use xmlsec with
a GNU GPL application or library?</h4>
<p>Probably, you will need to ask a lawyer. But IANAL answer can be found in the following table:</p>
<table style="text-align: left; width: 85%; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2">
<tbody>
<tr>
<td style="vertical-align: top; font-weight: bold;">XML Security Library module</td>
<td style="vertical-align: top; font-weight: bold;">Dependencies</td>
<td style="vertical-align: top; font-weight: bold;">Dependencies Licenses</td>
<td style="vertical-align: top; font-weight: bold;">Using with proprietary code</td>
<td style="vertical-align: top; font-weight: bold;">Using with MIT/BSD code</td>
<td style="vertical-align: top; font-weight: bold;">Using with GPL code</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-core</td>
<td style="vertical-align: top;">
<a href="http://xmlsoft.org">LibXML2</a>,
<a href="http://xmlsoft.org/XSLT">LibXSLT</a>
</td>
<td style="vertical-align: top;">MIT License</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-openssl</td>
<td style="vertical-align: top;"><a href="http://www.openssl.org">OpenSSL</a></td>
<td style="vertical-align: top;"><a href="https://www.openssl.org/source/license.html">OpenSSL licenses</a></td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">It's complicated, see <a href="https://www.openssl.org/docs/faq.html#LEGAL">OpenSSL FAQ</a> for more details</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-nss</td>
<td style="vertical-align: top;"><a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a></td>
<td style="vertical-align: top;">MPLv2</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-gnutls</td>
<td style="vertical-align: top;"><a href="http://www.gnu.org/software/gnutls/">GnuTLS</a></td>
<td style="vertical-align: top;">LGPLv2.1+</td>
<td style="vertical-align: top;">It's complicated, talk to a lawyer</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-mscrypto and xmlsec-mscng</td>
<td style="vertical-align: top;">Windows OS</td>
<td style="vertical-align: top;">Microsoft licensing, part of Windows OS.</td>
<td style="vertical-align: top;">It's complicated, talk to a lawyer</td>
<td style="vertical-align: top;">It's complicated, talk to a lawyer</td>
<td style="vertical-align: top;">It's complicated, talk to a lawyer</td>
</tr>
<tr>
<td style="vertical-align: top;">xmlsec-gcrypt</td>
<td style="vertical-align: top;"><a href="https://gnupg.org/software/libgcrypt/">LibGCrypt</a></td>
<td style="vertical-align: top;">LGPLv2.1+</td>
<td style="vertical-align: top;">It's complicated, talk to a lawyer</td>
<td style="vertical-align: top;">Yes</td>
<td style="vertical-align: top;">Yes</td>
</tr>
</tbody>
</table>
<p>
If you have questions about XML Security Library licensing then feel free to send these questions
to the <a href="mailing-list.html">mailing list</a>.
</p>
</div>
<div>
<h3>2. Building XMLSec.</h3>
<h4>
<a name="section_2_1"></a>2.1. Where can I get xmlsec?</h4>
<p>See XML Security Library <a href="http://www.aleksey.com/xmlsec/">download page</a>.</p>
<h4>
<a name="section_2_2"></a>2.2. How to compile xmlsec?</h4>
<p>On Unix just follow the "standard":</p>
<blockquote><code>
gunzip -c xmlsec-<version>.tar.gz | tar xvf - <br>
cd xmlsec-<version> <br>
mkdir build <br>
cd build <br>
../configure --help <br>
../configure [configure options] <br>
make <br>
make check <br>
make install
</code></blockquote>
<p>
On Windows the process is more complicated. Please check readme file in
the <code>xmlsec-<version>/win32</code> folder.
</p>
<h4>
<a name="section_2_3"></a>2.3. What other libraries are needed to compile/install xmlsec?</h4>
<p>See <a href="download.html">Download page</a> for detailed list.</p>
<h4>
<a name="section_2_4"></a>2.4. Why does make check fail for some tests?</h4>
<p>
The most likely reason is that some features might require additional configuration (e.g. installing
and configuring GOST plugins for OpenSSL and MSCrypto). Otherwise, please submit
a <a href="http://www.aleksey.com/xmlsec/bugs.html">bug report</a> and I'll try to fix it.
</p>
<h4>
<a name="section_2_5"></a>2.5. I got the xmlsec source code from GitHub and there is
no <code>configure</code> script. Where can I get it?</h4>
<p>The <code>configure</code> (and several other files) are generated. Use the
<code>autogen.sh</code> script to regenerate these files:</p>
<blockquote><code>
mkdir build <br>
cd build <br>
../autogen.sh [configure options] <br>
make <br>
...
</code></blockquote>
<h4>
<a name="section_2_6"></a>2.6. I do not need all these features supported by xmlsec. Can I disable
some of them?</h4>
<p>Yes, you can. Please run <code>configure --help</code> for the list of possible configuration options. </p>
<h4>
<a name="section_2_7"></a>2.7. I am compiling XMLSec library on Windows and it does not compile or crashes
right after the launch. Can you help me?</h4>
<p>There are several possible reasons why you might have problems on Windows:</p>
<ul>
<li>
<b>Incorrect MS C runtime libraries.</b>
Windows basically has multiple C runtimes. First, there is one called <code>libc.lib</code> and it can
only be linked to statically. The other is called <code>msvcrt.dll</code> and can only be linked
to dynamically. The first one occurs in its single-threaded and multithreaded variants.
Then for each of the libraries above, there are both debug and release version (we are at <b>six</b>
runtimes!). Next, different versions of Microsoft Visual C/C++ have different runtimes
which aren't compatible with each other (e.g. MSVC 6.0 runtime is not compatible with .NET 2003 runtime).
The rule is simple: exactly the same runtime must be used throughout the application and <b>all</b>
the librareies used by the application (e.g. XMLSec, LibXML2, LibXSLT, ...).
</li>
<li>
<b>Mismatched compilation parameters.</b>
The XMLSec library and the application should use the <b>same</b> defines. For example, when linking
statically, the <code>#define XMLSEC_STATIC</code> or <code>/DXMLSEC_STATIC=1</code> should be used
(and same applies to <code>LIBXML_STATIC</code> and <code>LIBXSLT_STATIC</code> defines). These defines
are critical on Windows (e.g. to ensure <code>__declspec(dllimport)</code> is done correctly) but have
no effect on Unix.
</li>
</ul>
</div>
<div>
<h3>3. Using XMLSec.</h3>
<h4>
<a name="section_3_1"></a>3.1. xmlSecDSigCtxValidate() function returned 0. Does this mean that the signature is valid?</h4>
<p><b>No!</b> The <code>xmlSecDSigCtxValidate()</code> function returns 0 when there are no <i>processing</i>
errors during signature validation (i.e. the document has correct syntax, all keys were found, etc.).
The signature is valid if and only if the <code>xmlSecDSigCtxValidate()</code> function returns 0 <b> and</b>
the <code>status</code> member of the <code>xmlSecDSigCtx</code> structure is equal to <code>xmlSecDSigStatusSucceeded</code>.
</p>
<h4>
<a name="section_3_2"></a>3.2. I am trying to sign use a part of XML document using an "Id" attribute but
it does not work. Do you support "Id" attributes at all?</h4>
<p>Yes, the <code>Id</code> attributes are supported by both XMLSec and LibXML2 libraries. However, you have to
tell LibXML2/XMLSec what is the name of the ID attribute. XML specification does not require ID attribute to
have name "ID", "Id" or "id". It can be anything you want! There are several ways to declare an ID attribute:</p>
<ul>
<li>
<b>Use DTD.</b> For example, the following DTD declares <code>Id</code> attribute in <code>Data</code> node to be
an XML ID attribute:
<blockquote><code>
<!DOCTYPE test [<br>
<!ATTLIST Data Id ID #IMPLIED><br>
]>
</code></blockquote>
The DTD might be directly included in the XML file or located in a standalone file. In the second case, you might
load the DTD in <a href="xmlsec-man.html">xmlsec command line utility</a> with the <code>--dtd-file</code> option.
</li>
<li>
<b>Use xml:id.</b> The <a href="http://www.w3.org/TR/xml-id/">xml:id</a> spec allows to declare
an ID attribute in the schema or DTD.
</li>
<li>
<b>Use --id-attr for <a href="xmlsec-man.html">xmlsec command line utility</a>.</b> The <code>--id-attr</code> command
line option allows to quickly declare an ID attribute for <a href="xmlsec-man.html">xmlsec command line utility</a>.
</li>
<li>
<b>Use xmlAddID function.</b> If you are writing an application, you can declare an ID attribute using
the <code>xmlAddID</code> LibXML2 function.
</li>
</ul>
<h4>
<a name="section_3_3"></a>3.3.<span style="font-weight: bold;"> </span>I am trying to sign an XML document and
I have a warning about "empty nodes set". Should I worry about this?</h4>
<p>Most likely <b>yes</b>. When it's not an error from specification point of view, I can hardly imagine
a real world case that requires signing an empty nodes set (i.e. signing an empty string). Most likely,
you have this error because you are trying to use an ID attribute and you did not declare the ID attribute
(see <a href="faq.html#section_3_2">section 3.2</a> about ID attributes).</p>
<h4>
<a name="section_3_4"></a>3.4. I am trying to sign/validate a document but xmlXPtrEval function can't
evaluate "xpointer(id('XXXXXXX'))" expression. What's wrong?</h4>
<p>First of all, read <a href="#section_3_2">section 3.2</a> about ID attributes. If you have tried to declare
the required ID attribute and you still have problems then it is likely working with the Visa 3D protocol.
This protocol tries to reference to an "id" attribute defined as CDATA instead of ID in the DTD (it is
impossible in XML as described in <a href="#section_3_2">section 3.2</a>). Even worse, the value of the
Visa 3D "id" attribute may start from number or contain "+" or "/" and this breakes the
<a href="http://www.w3.org/TR/REC-xml#sec-attribute-types">XML specification</a> again. The right solution
for this problem is to change Visa 3D protocol. As a practical soluton, try (on your own risk) the "Visa 3D hack"
in xmlsec:</p>
<ul>
<li>
First, register ID attributes manually (using either <code>xmlAddID</code> function or
<code>--id-attr</code> option for <a href="xmlsec-man.html">xmlsec command line utility</a>).
</li>
<li>
Second, enable the "Visa 3D hack" in XML DSig context (using either <code>dsigCtx->flags |= XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK</code>
or <code>--enable-visa3d-hack</code> option for <a href="xmlsec-man.html">xmlsec command line utility</a>).
</li>
</ul>
<p><b>This is a hack. You are warned!</b></p>
<p><b>UPDATE:</b> It appears that newer version (Novemeber, 2005) of the Visa3D DTD has this problem fixed and
now "id" attribute is declared as ID correctly.
</p>
<h4>
<a name="section_3_5"></a>3.5. The XMLSec library or XMLSec command line tool fails because the key cannot be found. What's wrong?</h4>
<p>There might be multiple reasons for the "key cannot be found error":</p>
<ul>
<li>
<b>KeyValue or DEREncodedKeyValue nodes are disabled by default.</b> The <code>KeyValue</code> and <code>DEREncodedKeyValue</code>
nodes allow definition of the key value directly in an XML file. This creates a security risk because there is no mechanism
to verify the key origin (and for example, this enables to create "fake" signatures). Thus, the <code>KeyValue</code> and
<code>DEREncodedKeyValue</code> nodes are disabled by default. Yet, in some use cases the use of these nodes in XML file
can be appropriate. If you verify that these nodes do not present security concerns for your applicaton, then you can
re-enable <code>KeyValue</code> and <code>DEREncodedKeyValue</code> nodes using the <code>--enabled-key-data</code> option
for the <a href="xmlsec-man.html">xmlsec command line utility</a>, or by setting the <code>keyInfoCtx->enabledKeyData</code>
parameter in your application.
<b>THIS IS NOT SECURE AND NOT RECOMMENDED.</b>
</li>
<li>
<b>Key is not referenced in KeyInfo node (or this node is not included).</b> If a key is not referenced in the XML file then it
creates a potential security risk because the key is no longer coupled with signature (the <code>KeyInfo</code> node is signed
during the XML signature process and it's integrity is validated during XML signature verification). Yet, in some use cases not
using the <code>KeyInfo</code> node to specifiy the key can be appropriate. If you verify that this does not present a security
concerns for your applicaton, then you can enable "lax" key search mode by using <code>--lax-key-search</code> option for the
<a href="xmlsec-man.html">xmlsec command line utility</a>, or by setting <code>keyInfoCtx->flags |= XMLSEC_KEYINFO_FLAGS_LAX_KEY_SEARCH;</code>
flag in your application.
<b>THIS IS NOT SECURE AND NOT RECOMMENDED.</b>
</li>
<li>
<b>Certificate cannot be verified.</b> See the next <a href="#section_3_6">question 3.6</a> in this FAQ.
</li>
</ul>
<h4>
<a name="section_3_6"></a>3.6. The XMLSec library or XMLSec command line tool fails because the certificate cannot be
verified. What's wrong?</h4>
<p>There might be several reasons why XMLSec library cannot verify a certificate:</p>
<ul>
<li>
First, check that both trusted (root) and untrusted certificates from the certificate chain are provided to
the XMLSec library or command line tool (e.g. in the XML file, or loaded into the keys manager,
or available in the crypto library ceritificates store, or provided in the command line, or ...).
</li>
<li>
Check if any of the certificates in the certificate verification chain expired.
The <a href="http://www.w3.org/Signature">XML Digital Signature</a> specification does not have a standard way
to include the signature timestamp. If you decide to add timestamp to your signature, then consider
signing the timestamp along with other data. If you verify that changing signature verification time from "now"
to some other value does not present a security concerns for your applicaton, then you can use
<code>--verification-time <time></code> option (where <code><time></code> is the local system
time in the <code>YYYY-MM-DD HH:MM:SS</code> format), or by setting <code>keyInfoCtx->certsVerificationTime</code>
parameter in your application.
</li>
<li>
Older certificates that use MD5 or SHA1 hashes might be rejected by newer cryptographic libraries because these
algorithms are no longer considered secure. If you verify that this does not present a security concerns for your applicaton,
then you can re-enable these algorithms (and also skip some other strict certificate verification checks) by using the
<code>--X509-skip-strict-checks</code> option for the <a href="xmlsec-man.html">xmlsec command line utility</a>, or by setting
<code>keyInfoCtx->flags |= XMLSEC_KEYINFO_FLAGS_X509DATA_SKIP_STRICT_CHECKS;</code> flag in your application.
<b>THIS IS NOT SECURE AND NOT RECOMMENDED.</b>
</li>
<li>
Lastly, you can use the <code>--insecure </code> option for the <a href="xmlsec-man.html">xmlsec command line utility</a>,
or by set <code>keyInfoCtx->flags |= XMLSEC_KEYINFO_FLAGS_X509DATA_DONT_VERIFY_CERTS;</code> flag in your application to
completely disable the certificates verification. Disabling certificate verification creates a security risk because
there is no mechanism to verify the key origin (and for example, this enables to create "fake" signatures).
<b>THIS IS NOT SECURE AND NOT RECOMMENDED.</b>
</li>
</ul>
<h4>
<a name="section_3_7"></a>3.7. I really like the XMLSec library but it is based on OpenSSL and I have to use another crypto library in my application. Can you write code to support my crypto library?</h4>
<p>The XMLSec library has a very modular structure and there should be no problem with using another crypto library.
For example, XMLSec already supports NSS, GnuTLS, GCrypt and multple Microsoft Crypto APIs. If your favorite cryptographic
library is not supported by XMLSec then you can either write intergration yourself or contact me to discuss possible options.
</p>
<h4>
<a name="section_3_8"></a>3.8. I really like the XMLSec library but it does not have cipher or transform that I need. Can you write code for me?</h4>
<p>The XMLSec library has a very modular structure and it is easy to add any cipher or other transform. You can either
write intergration yourself or contact me to discuss possible options.
</p>
</div>
</td></tr></table></td>
</tr></table></body>
</html>
|
