summaryrefslogtreecommitdiff
path: root/docs/faq.html
blob: cb99d8bded129f64f7e0ebf1f48fd3bb4d43ec7c (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
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
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"><html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>XML Security Library: Documentation</title></head><body><table witdh="100%" valign="top"><tbody><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>
<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>
<ul><li><a href="http://www.aleksey.com/xmlsec/xmldsig-verifier.html">Online Verifier</a></li></ul>
<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="http://www.aleksey.com/pipermail/xmlsec">Mailing list</a></li>
<li><a href="related.html">Related</a></li>
</ul>
<table width="100%">
<tbody><tr>
<td width="15"><br>
</td>
<td><a href="http://xmlsoft.org/"><img src="images/libxml2-logo.png" alt="LibXML2" border="0"></a></td>
</tr>
<tr>
<td width="15"><br>
</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"><br>
</td>
<td><a href="http://www.openssl.org/"><img src="images/openssl-logo.png" alt="OpenSSL" border="0"></a></td>
</tr>
</tbody></table>
</td>
<td valign="top"><table width="100%" valign="top">
<tbody><tr><td valign="top" align="left" id="xmlsecContent">
<div align="center">                                          
      <h1>Frequently Asked Questions</h1>
      </div>
<h3>0. Why have you wrote xmlsec?</h3>
<p>
      Very simple: when I decided to understand the 
      <a href="http://www.w3.org/Signature/">XML Digital Signature</a>
      and <a href="http://www.w3.org/Encryption/">XML Encrytpion</a> 
      specs there were no open source C/C++ implementation available.
      After spending a couple days trying to install Java implementation
      (Apache XML Security Suite) I gave up and decided to implement 
      these specs by myself.
      </p>
<h3>1. License(s).</h3>
<h4>1.1. Licensing Terms for xmlsec.</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>1.2. Can I use xmlsec with proprietary application or library? Can I use xmlsec with a GNU GPL application or library?</h4>

XML Security Library is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT license</a>
which
allows you to link it with proprietary applications as well as with
GPLed code. However, xmlsec library is based on other libraries and you
should look at all the licenses to get the full picture. The table
bellow summarizes my understanding of the situation for few most
popular cases. You might want to
talk with your lawyer to confirm that this information is correct or to
get an advice if your license is not covered in this table.<br>
            <br>


            <table cellpadding="2" cellspacing="2" border="1" style="text-align: left; width: 85%; margin-left: auto; margin-right: auto;">

  <tbody>
    <tr>
      <td style="vertical-align: top; font-weight: bold;">XML Security Library module<br>
      </td>
      <td style="vertical-align: top; font-weight: bold;">Dependencies<br>
      </td>
      <td style="vertical-align: top; font-weight: bold;">Dependencies License<br>
      </td>
      <td style="vertical-align: top; font-weight: bold;">Using with proprietary
applications/libraries<br>
      </td>
      <td style="vertical-align: top; font-weight: bold;">Using with MIT/BSD&nbsp; applications/libraries <br>
                  </td>
<td style="vertical-align: top; font-weight: bold;">Using with GPL
applications/libraries<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">xmlsec-core<br>
      </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;"><a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a></td>
      <td style="vertical-align: top;">Yes.<br>
      </td>
      <td style="vertical-align: top;">Yes.<br>
                  </td>
<td style="vertical-align: top;">Yes.<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">xmlsec-openssl (also requires
xmlsec-core library)<br>
      </td>
      <td style="vertical-align: top;"><a href="http://www.openssl.org">OpenSSL<br>
      </a></td>
      <td style="vertical-align: top;">OpenSSL License<br>
      </td>
      <td style="vertical-align: top;">Yes.<br>
      </td>
      <td style="vertical-align: top;">Yes.</td>
<td style="vertical-align: top;">May be. <a href="http://www.openssl.org/support/faq.cgi#LEGAL2">OpenSSL FAQ</a>&nbsp;
states that OpenSSL library is covered by a <a href="http://www.gnu.org/licenses/gpl-faq.html#WritingFSWithNFLibs">special
GPL exception</a> thus it could be used in GPLed
applications/libraries. However, some people think that this is not
true (<a href="http://lists.debian.org/debian-legal/2002/debian-legal-200210/msg00173.html">one</a>
and <a href="http://lists.debian.org/debian-legal/2002/debian-legal-200205/msg00127.html">two</a>).
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">xmlsec-gnutls (also requires
xmlsec-core library) </td>
      <td style="vertical-align: top;"><a href="http://www.gnu.org/software/gnutls/">GnuTLS</a><br>
      </td>
      <td style="vertical-align: top;"><a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a><br>
      </td>
      <td style="vertical-align: top;">Yes, but only if the&nbsp; application is not distributed.<br>
      </td>
      <td style="vertical-align: top;">Yes.</td>
<td style="vertical-align: top;">Yes.<br>
      </td>
    </tr>
    <tr>
      <td style="vertical-align: top;">xmlsec-nss (also requires
xmlsec-core library) </td>
      <td style="vertical-align: top;"><a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a><br>
      </td>
      <td style="vertical-align: top;">Dual licensing: <a href="http://www.opensource.org/licenses/mozilla1.0.php">Mozilla
Public License</a> and <a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a>
      </td>
      <td style="vertical-align: top;">Yes.<br>
      </td>
      <td style="vertical-align: top;">Yes.</td>
<td style="vertical-align: top;">Probably yes, but at the time I
am writing this there are some <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=217162">unresolved
issues</a>.<br>
      </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="bugs.html">mailing list</a>.<br>
            </p>
            <h3>2. Installation.</h3>

<h4>2.1. Where can I get xmlsec?</h4>
<p>
      The original distribution comes from 
      <a href="http://www.aleksey.com/xmlsec/">XML Security Library page</a>.
      Also xmlsec is available from 
      <a href="ftp://rpmfind.net/pub/libxml/xmlsec">rpmfind.net miror</a>.

      </p>
<h4>2.2. How to compile xmlsec?</h4>
<p>
      On Unix just follow the "standard":
         </p>
<blockquote>
	 <code>gunzip -c xmlsec-xxx.tar.gz | tar xvf -</code><br>
	 <code>cd xmlsec-xxxx</code><br>
	 <code>./configure --help</code><br>
	 <code>./configure [possible options] </code><br>
	 <code>make</code><br>
	 <code>make check</code><br>
	 <code>make install</code>
	 </blockquote>
<p>
      At that point you may have to rerun ldconfig or similar utility to update your 
      list of installed shared libs.<br>
      On Windows the process is more complicated. Please check
      readme file in <code>xmlsec-xxxx/win32</code> folder.

      </p>
<h4>2.3. What other libraries are needed to compile/install xmlsec?</h4>
<p>
      The XML Security Library requires:
</p>
<ul>
<li><a href="http://xmlsoft.org/downloads.html">LibXML</a></li>
         <li>
<a href="http://xmlsoft.org/XSLT/downloads.html">LibXSLT</a> (optional)</li>
</ul>
<ul>
<li>
<a href="http://www.openssl.org/">OpenSSL</a> version 0.9.7 
	 (prefered) or version 0.9.6.
        </li>
	<li>
<a href="http://www.gnu.org/software/gnutls/">GnuTLS</a>
	and <a href="http://www.gnu.org/directory/security/libgcrypt.html">Libgcrypt</a> - 
	GNU SSL and cryptographic libraries.
	</li>
        <li>
<a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a> -
	Mozilla cryptographic library.
	</li>
    </ul>
<h4>2.4. Why does make check fail for some tests?</h4>
<p>
      First of all, some tests <b>must</b> fail! Please read the 
      messages printed before the tests.<br>
      If you have other failed tests then the next possible reason
      is that you use OpenSSL 0.9.6 and some xmlsec features are
      disabled in this case. Please try to upgrade to OpenSSL 0.9.7
      and re-configure/re-compile xmlsec.<br>
      if this does not help then probably there is a bug in the xmlsec
      or in the xmlsec tests. Please submit the 
      <a href="http://www.aleksey.com/xmlsec/bugs.html">bug report</a>
      and I'll try to fix it.

      </p>
<h4>2.5. I get the xmlsec sources from CVS and there is no 
      configure script. Where can I get it?</h4>
<p>
      The configure (and other Makefiles) are generated. Use the 
      <code>autogen.sh</code> script to regenerate the configure 
      and Makefiles, like:
	</p>
<blockquote>   
    	<code>./autogen.sh --prefix=/usr</code>
        </blockquote>
<h4>2.5. 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>2.6. I am compiling XMLSec library on Windows and 
      it does not compile (crashes right after the launch). 
      Can you help me?</h4>
<p>
      There are several possible reasons why you might have problems
      on Windows. All of them originated in the MS C compiler/linker 
      and are specific to Windows. Thanks to Igor Zlatkovic for writing these
      long explanations. 
      
      </p>
<p>
<b>1) Incorrect MS C runtime libraries.</b>
      </p>
<p>Windows basically has two C runtimes. The one is called libc.lib and 
      can only be linked to statically. The other is called msvcrt.dll and 
      can only be linked to dynamically. The first one occurs in its 
      single-threaded and multithreaded variant, which gives three 
      different runtimes. These three then live in their debug and 
      release incarnations, which results in six C runtimes.
      The rule is simple: exactly the same runtime must be used throughout 
      the application. Client code must use the same runtime as XMLSec, 
      LibXML, LibXSLT, OpenSSL or any other library used.<br> 
      
      If you downloaded XMLSec, LibXML, LibXSLT and OpenSSL binaries
      from Igor's <a href="http://www.zlatkovic.com/projects/libxml/index.html">page</a>
      then all libraries are all linked to msvcrt.dll (Multithreaded DLL;
      /MD compiler switch). 
      The click-next click-finish wizardry from Visual Studio chooses the 
      single-threaded libc.lib as the default when you create a new project. 
      And this causes great problems because you program crashes on first 
      IO operation, first malloc/free from different runtimes or something
      even more trivial.<br>
      
      Do not forget that tf you need a different runtime for some reason, 
      then you MUST recompile not only XMLSec, but LibXML, LibXSLT and 
      OpenSSL as well.
      
      </p>
<p>
<b>2) Static linking without correct defines.</b>
      </p>
<p>When people link statically to XMLSec, then they must 
      <code>#define XMLSEC_STATIC</code> in their source files before 
      including any XMLSec header. Almost none is doing that :) 
      This macro has no effect on Unix, but it is vital on Windows.<br>
      
      This applies to LibXML and LibXSLT as well, no matter if 
      these are used directly or not. If just XMLSec is used, but 
      everything is linked statically, then there must be a
        </p>
<blockquote><code>
        #define LIBXML_STATIC<br>
	#define LIBXSLT_STATIC<br>
	#define XMLSEC_STATIC<br></code></blockquote>
<p>
      before any xmlsec header is included. Even if the client code 
      doesn't call into libxml at all, still this must be defined. 
      XMLSec headers will include LibXML headers and they must have 
      these definitions. Without them, every variable XMLSec includes from 
      LibXML headers will have <code>__declspec(dllimport)</code> 
      prepended and that will give headaches if static LibXML is used 
      for linking.<br>
      
      This scheme makes it possible to have any combination of static and 
      dynamic libraries in the resulting executable. Its cost is the need 
      to <code>#define</code> apropriate macros. People would ideally define 
      them by using the compiler's <code>/D</code> switch in projects that 
      link statically.
	    
      </p>
<h3>3. Developing with XMLSec.</h3>
<h4>3.1. xmlSecDSigCtxValidate() function returned 0. Does this mean
      that the signature is valid?</h4>
<b>No!</b><p> Function xmlSecDSigCtxValidate() returns 0 when there
      were 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 xmlSecDSigCtxValidate() 
      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>3.2. 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 ID attribute and you do not provide a DTD for the document.
      For example, the following Reference element:
        </p>
<blockquote><code>
	  &lt;?xml version="1.0" encoding="UTF-8"&gt;<br>
	  &lt;Root&gt;<br>
	  &nbsp;&nbsp;&lt;Data Id="1234"&gt;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;The data I want to sign<br>
	  &nbsp;&nbsp;&lt;/Data&gt;<br>
	  &nbsp;&nbsp;&lt;Signature xmlns="http://www.w3.org/2000/09/xmldsig#"&gt;<br>
	  &nbsp;&nbsp;...<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;&lt;Reference URI="#1234"&gt;<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;...<br>
	  &nbsp;&nbsp;&nbsp;&nbsp;&lt;/Reference&gt;<br>
	  &nbsp;&nbsp;...<br>
	  &nbsp;&nbsp;&lt;/Signature&gt;<br>
	  &lt;/Root&gt;<br></code></blockquote>
<p>
      always results in an empty nodes set (and an empty string signed!) unless
      you have a DTD that declares <code>Id</code> attribute of the 
      <code>Data</code> element to be an ID attribute:
        </p>
<blockquote><code>
	&lt;!DOCTYPE test [<br>
	&nbsp;&lt;!ATTLIST Data Id ID #IMPLIED&gt;<br>
	]&gt;<br></code></blockquote>
<p>
      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 xmlsec command line utility with "--dtd-file" option.
</p>
<p>
      If you are using XML Security Library in your application (not the xmlsec
      command line utility!) then you can do a "hack" and tell LibXML2 (and
      XMLSec) which attributes are ID attributes without providing a DTD
      by calling <code>xmlAddID</code> function. However, this might 
      make you signature non-interoperable with other XMLDSig implementations.

      </p>
<h4>3.3. I have a document signed with a certificate that is now expired.
      Can I verify this signature?</h4>
<p>
      Yes, you can. However, you need to be carefull. Most likely you
      do want to make sure that the certificate was not expired 
      when the document was signed. The <a href="http://www.w3.org/Signature">XML 
      Digital Signature</a> specification does not have a standard
      way to include the signature timestamp. Which means that you need 
      to define where to put timestamp by yourself. Please note, that 
      the timestamp <b>must</b> be signed along with the other data.<br>
      Finaly set the desired verification time in <code>certsVerificationTime</code> 
      member of the <code>xmlSecKeyInfoCtx</code> structure.
</p>
<p> 
      If you are using xmlsec command line utility then you can use 
      <code>--verification-time &lt;time&gt;</code> option (where
      <code>&lt;time&gt;</code> is the local system time in the 
      "<code>YYYY-MM-DD HH:MM:SS</code>" format).
      
      </p>
<h4>3.4. 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 <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>
      and <a href="http://www.gnu.org/software/gnutls/gnutls.html">GnuTLS</a>.
      Check the latest release and/or the mailing list and you might find 
      that your library is already supported or someone working on it.<br>
      If you are not so lucky, then you can either write some code by yourself
      or contact me in private email to discuss possible options.      
</p>
<h4>3.5. 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 there should be easy
      to add any cipher or other transform. Again, you can either write some
      code by yourself or try to talk to me in private email.
</p>
</td></tr>
<tr><td>
<br><br><p><a href="bugs.html">Aleksey Sanin</a></p>
</td></tr>
</tbody></table></td>
</tr></tbody></table></body></html>