docs/faq.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   4 <title>XML Security Library: Documentation</title>
   5 </head>
   6 <body><table witdh="100%" valign="top"><tr valign="top">
   7 <td valign="top" align="left" width="210">
   8 <img src="images/logo.gif" alt="XML Security Library" border="0"><p></p>
   9 <ul>
  10 <li><a href="index.html">Home</a></li>
  11 <li><a href="download.html">Download</a></li>
  12 <li><a href="news.html">News</a></li>
  13 <li><a href="documentation.html">Documentation</a></li>
  14 <ul>
  15 <li><a href="faq.html">FAQ</a></li>
  16 <li><a href="api/xmlsec-notes.html">Tutorial</a></li>
  17 <li><a href="api/xmlsec-reference.html">API reference</a></li>
  18 <li><a href="api/xmlsec-examples.html">Examples</a></li>
  19 </ul>
  20 <li><a href="xmldsig.html">XML Digital Signature</a></li>
  21 <ul><li><a href="http://www.aleksey.com/xmlsec/xmldsig-verifier.html">Online Verifier</a></li></ul>
  22 <li><a href="xmlenc.html">XML Encryption</a></li>
  23 <li><a href="c14n.html">XML Canonicalization</a></li>
  24 <li><a href="bugs.html">Reporting Bugs</a></li>
  25 <li><a href="http://www.aleksey.com/pipermail/xmlsec">Mailing list</a></li>
  26 <li><a href="related.html">Related</a></li>
  27 <li><a href="authors.html">Authors</a></li>
  28 </ul>
  29 <table width="100%">
  30 <tr>
  31 <td width="15"></td>
  32 <td><a href="http://xmlsoft.org/"><img src="images/libxml2-logo.png" alt="LibXML2" border="0"></a></td>
  33 </tr>
  34 <tr>
  35 <td width="15"></td>
  36 <td><a href="http://xmlsoft.org/XSLT"><img src="images/libxslt-logo.png" alt="LibXSLT" border="0"></a></td>
  37 </tr>
  38 <tr>
  39 <td width="15"></td>
  40 <td><a href="http://www.openssl.org/"><img src="images/openssl-logo.png" alt="OpenSSL" border="0"></a></td>
  41 </tr>
  42 <!--Links - start--><!--Links - end-->
  43 </table>
  44 </td>
  45 <td valign="top"><table width="100%" valign="top"><tr><td valign="top" align="left" id="xmlsecContent">
  46 <div align="center">
  47             <h1>Frequently Asked Questions</h1>
  48             </div>
  49 <h3>0. Where can I read more about XML Signature and XML
  50 Encryption?</h3>
  51 <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
  52 help you get started.<br></p>
  53 <h3>1. License(s).</h3>
  54 <h4> <a name="section_1_1"></a>1.1. Licensing Terms for
  55 xmlsec.</h4>
  56 <p> XML Security Library is released under the <a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a>,
  57 see the file Copyright in the distribution for the precise wording. </p>
  58 <h4> <a name="section_1_2"></a>1.2. Can I use xmlsec with
  59 proprietary application or
  60 library? Can I use xmlsec with a GNU GPL application or library?</h4>
  61 <p>Probably, you will need to ask a lawyer. But not-a-lawyer answer
  62 can be found in the following table:
  63 </p>
  64 <table style="text-align: left; width: 85%; margin-left: auto; margin-right: auto;" border="1" cellpadding="2" cellspacing="2"><tbody>
  65 <tr>
  66 <td style="vertical-align: top; font-weight: bold;">XML
  67 Security Library module<br>
  68 </td>
  69                   <td style="vertical-align: top; font-weight: bold;">Dependencies<br>
  70 </td>
  71                   <td style="vertical-align: top; font-weight: bold;">Dependencies
  72 License<br>
  73 </td>
  74                   <td style="vertical-align: top; font-weight: bold;">Using
  75 with proprietary
  76 applications/libraries<br>
  77 </td>
  78                   <td style="vertical-align: top; font-weight: bold;">Using
  79 with MIT/BSD applications/libraries <br>
  80 </td>
  81                   <td style="vertical-align: top; font-weight: bold;">Using
  82 with GPL
  83 applications/libraries<br>
  84 </td>
  85                 </tr>
  86 <tr>
  87 <td style="vertical-align: top;">xmlsec-core<br>
  88 </td>
  89                   <td style="vertical-align: top;">
  90 <a href="http://xmlsoft.org">LibXML2</a>/<a href="http://xmlsoft.org/XSLT">LibXSLT</a>
  91                   </td>
  92                   <td style="vertical-align: top;"><a href="http://www.opensource.org/licenses/mit-license.html">MIT License</a></td>
  93                   <td style="vertical-align: top;">Yes.<br>
  94 </td>
  95                   <td style="vertical-align: top;">Yes.<br>
  96 </td>
  97                   <td style="vertical-align: top;">Yes.<br>
  98 </td>
  99                 </tr>
 100 <tr>
 101 <td style="vertical-align: top;">xmlsec-openssl (also
 102 requires
 103 xmlsec-core library)<br>
 104 </td>
 105                   <td style="vertical-align: top;"><a href="http://www.openssl.org">OpenSSL<br></a></td>
 106                   <td style="vertical-align: top;">OpenSSL License<br>
 107 </td>
 108                   <td style="vertical-align: top;">Yes.<br>
 109 </td>
 110                   <td style="vertical-align: top;">Yes.</td>
 111                   <td style="vertical-align: top;">May be. <a href="http://www.openssl.org/support/faq.cgi#LEGAL2">OpenSSL FAQ</a>
 112 states that OpenSSL library is covered by a <a href="http://www.gnu.org/licenses/gpl-faq.html#WritingFSWithNFLibs">special
 113 GPL exception</a> thus it could be used in GPLed
 114 applications/libraries. However, some people think that this is not
 115 true (<a href="http://lists.debian.org/debian-legal/2002/debian-legal-200210/msg00173.html">one</a>
 116 and <a href="http://lists.debian.org/debian-legal/2002/debian-legal-200205/msg00127.html">two</a>).
 117                   </td>
 118                 </tr>
 119 <tr>
 120 <td style="vertical-align: top;">xmlsec-gnutls (also
 121 requires
 122 xmlsec-core library) </td>
 123                   <td style="vertical-align: top;">
 124 <a href="http://www.gnu.org/software/gnutls/">GnuTLS</a><br>
 125 </td>
 126                   <td style="vertical-align: top;">
 127 <a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a><br>
 128 </td>
 129                   <td style="vertical-align: top;">Yes, but only if
 130 the application is not distributed.<br>
 131 </td>
 132                   <td style="vertical-align: top;">Yes.</td>
 133                   <td style="vertical-align: top;">Yes.<br>
 134 </td>
 135                 </tr>
 136 <tr>
 137 <td style="vertical-align: top;">xmlsec-nss (also
 138 requires
 139 xmlsec-core library) </td>
 140                   <td style="vertical-align: top;">
 141 <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a><br>
 142 </td>
 143                   <td style="vertical-align: top;">Dual licensing: <a href="http://www.opensource.org/licenses/mozilla1.0.php">Mozilla
 144 Public License</a> and <a href="http://www.opensource.org/licenses/gpl-license.php">GPL</a> </td>
 145                   <td style="vertical-align: top;">Yes.<br>
 146 </td>
 147                   <td style="vertical-align: top;">Yes.</td>
 148                   <td style="vertical-align: top;">Probably yes, but at
 149 the time I
 150 am writing this there are some <a href="http://bugzilla.mozilla.org/show_bug.cgi?id=217162">unresolved
 151 issues</a>.<br>
 152 </td>
 153                 </tr>
 154 <tr>
 155 <td style="vertical-align: top;">xmlsec-mscrypto
 156 (also requires
 157 xmlsec-core library) </td>
 158                   <td style="vertical-align: top;">
 159 <a href="http://msdn.microsoft.com/security/">MSCrypto API</a><br>
 160 </td>
 161                   <td style="vertical-align: top;">Microsoft licensing:
 162 The libraries are part of MS Windows, and are also distributed with
 163 Internet Explorer. </td>
 164                   <td style="vertical-align: top;">Unknown.<br>
 165 </td>
 166                   <td style="vertical-align: top;">Unknown.</td>
 167                   <td style="vertical-align: top;">Unknown.</td>
 168                 </tr>
 169 </tbody></table>
 170 <p>If you have questions about XML Security Library
 171 licensing then feel free to send these questions to the <a href="bugs.html">mailing list</a>.<br></p>
 172 <h3>2. Installation.</h3>
 173 <h4> <a name="section_2_1"></a>2.1. Where can I get xmlsec?</h4>
 174 <p> The original distribution comes from <a href="http://www.aleksey.com/xmlsec/">XML Security Library page</a>.
 175
 176 </p>
 177 <h4> <a name="section_2_2"></a>2.2. How to compile xmlsec?</h4>
 178 <p> On Unix just follow the "standard": </p>
 179 <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>
 180 <p> At that point you may have to rerun ldconfig or similar
 181 utility to update your list of installed shared libs.<br>
 182 On Windows the process is more complicated. Please check readme file in
 183             <code>xmlsec-xxxx/win32</code> folder. </p>
 184 <h4> <a name="section_2_3"></a>2.3. What other libraries
 185 are
 186 needed to compile/install
 187 xmlsec?</h4>
 188 <p> The XML Security Library requires: </p>
 189 <ul>
 190 <li><a href="http://xmlsoft.org/downloads.html">LibXML</a></li>
 191               <li>
 192 <a href="http://xmlsoft.org/XSLT/downloads.html">LibXSLT</a>
 193 (optional)</li>
 194             </ul>
 195 <ul>
 196 <li> <a href="http://www.openssl.org/">OpenSSL</a>
 197 version
 198 0.9.7 (prefered or later) or version 0.9.6. </li>
 199               <li>
 200 <a href="http://www.gnu.org/software/gnutls/">GnuTLS</a>
 201 and <a href="http://www.gnu.org/directory/security/libgcrypt.html">Libgcrypt</a>
 202 - GNU SSL and cryptographic libraries. </li>
 203               <li>
 204 <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a> -
 205 Mozilla cryptographic library. </li>
 206             </ul>
 207 <h4> <a name="section_2_4"></a>2.4. Why does make check
 208 fail
 209 for some tests?</h4>
 210 <p> First of all, some tests <b>must</b> fail! Please read
 211 the messages printed before the tests.<br>
 212 If you have other failed tests then the next possible reason is that
 213 you use OpenSSL 0.9.6 and some xmlsec features are disabled in this
 214 case. Please try to upgrade to OpenSSL 0.9.7 and
 215 re-configure/re-compile xmlsec.<br>
 216 if this does not help then probably there is a bug in the xmlsec or in
 217 the xmlsec tests. Please submit the <a href="http://www.aleksey.com/xmlsec/bugs.html">bug report</a> and I'll
 218 try to fix it. </p>
 219 <h4> <a name="section_2_5"></a>2.5. I get the xmlsec
 220 sources
 221 from CVS and there is no
 222 configure script. Where can I get it?</h4>
 223 <p> The configure (and other Makefiles) are generated. Use
 224 the <code>autogen.sh</code> script to regenerate the configure and
 225 Makefiles, like: </p>
 226 <blockquote> <code>./autogen.sh --prefix=/usr</code> </blockquote>
 227 <h4> <a name="section_2_6"></a>2.6. I do not need all
 228 these
 229 features supported by
 230 xmlsec. Can I disable some of them?</h4>
 231 <p> Yes, you can. Please run <code>./configure --help</code>
 232 for the list of possible configuration options. </p>
 233 <h4> <a name="section_2_7"></a>2.7. I am compiling XMLSec
 234 library on Windows and it
 235 does not compile (crashes right after the launch). Can you help me?</h4>
 236 <p> There are several possible reasons why you might have
 237 problems on Windows. All of them originated in the MS C compiler/linker
 238 and are specific to Windows. Thanks to Igor Zlatkovic for writing these
 239 long explanations. </p>
 240 <p> <b>1) Incorrect MS C runtime libraries.</b> </p>
 241 <p>Windows basically has two C runtimes. The one is called
 242 libc.lib and can only be linked to statically. The other is called
 243 msvcrt.dll and can only be linked to dynamically. The first one occurs
 244 in its single-threaded and multithreaded variant, which gives three
 245 different runtimes. These three then live in their debug and release
 246 incarnations, which results in six C runtimes. Worse, different versions
 247 of Microsoft Visual C/C++ have different runtimes (e.g. MSVC 6.0
 248 runtime is not compatible with .NET 2003 runtime). The rule is simple:
 249 exactly the same runtime must be used throughout the application.
 250 Client code must use the same runtime as XMLSec, LibXML, LibXSLT,
 251 OpenSSL or any other library used.<br>
 252 If you downloaded XMLSec, LibXML, LibXSLT and OpenSSL binaries from
 253 Igor's <a href="http://www.zlatkovic.com/projects/libxml/index.html">page</a>
 254 then all libraries are all linked to msvcrt.dll (Multithreaded DLL; /MD
 255 compiler switch). The click-next click-finish wizardry from Visual
 256 Studio chooses the single-threaded libc.lib as the default when you
 257 create a new project. And this causes great problems because you
 258 program crashes on first IO operation, first malloc/free from different
 259 runtimes or something even more trivial.<br>
 260 Do not forget that tf you need a different runtime for some reason,
 261 then you MUST recompile not only XMLSec, but LibXML, LibXSLT and
 262 OpenSSL as well. </p>
 263 <p> <b>2) Static linking without correct defines.</b> </p>
 264 <p>When people link statically to XMLSec, then they must <code>#define
 265 XMLSEC_STATIC</code> in their source files before including any XMLSec
 266 header. Almost none is doing that :) This macro has no effect on Unix,
 267 but it is vital on Windows.<br>
 268 This applies to LibXML and LibXSLT as well, no matter if these are used
 269 directly or not. If just XMLSec is used, but everything is linked
 270 statically, then there must be a </p>
 271 <blockquote><code> #define LIBXML_STATIC<br>
 272 #define LIBXSLT_STATIC<br>
 273 #define XMLSEC_STATIC<br></code></blockquote>
 274 <p> before any xmlsec header is included. Even if the
 275 client code doesn't call into libxml at all, still this must be
 276 defined. XMLSec headers will include LibXML headers and they must have
 277 these definitions. Without them, every variable XMLSec includes from
 278 LibXML headers will have <code>__declspec(dllimport)</code> prepended
 279 and that will give headaches if static LibXML is used for linking.<br>
 280 This scheme makes it possible to have any combination of static and
 281 dynamic libraries in the resulting executable. Its cost is the need to <code>#define</code>
 282 apropriate macros. People would ideally define them by using the
 283 compiler's <code>/D</code> switch in projects that link statically. </p>
 284 <h3>3. Developing with XMLSec.</h3>
 285 <h4> <a name="section_3_1"></a>3.1.
 286 xmlSecDSigCtxValidate()
 287 function returned 0. Does
 288 this mean that the signature is valid?</h4>
 289 <b>No!</b><p> Function xmlSecDSigCtxValidate() returns 0 when there
 290 were no <i>processing</i> errors during signature validation (i.e. the
 291 document has correct syntax, all keys were found, etc.). The signature
 292 is valid if and only if the xmlSecDSigCtxValidate() function returns 0 <b>and</b>
 293 the <code>status</code> member of the <code>xmlSecDSigCtx</code>
 294 structure is equal to <code>xmlSecDSigStatusSucceeded</code>. </p>
 295 <h4> <a name="section_3_2"></a>3.2. I am trying to sign
 296 use a
 297 part of XML document using an "Id" attribute but it does not work. Do
 298 you support "Id" attributes at all?</h4>
 299 <p><span style="font-weight: bold;">Yes. </span>LibXML2
 300 and XMLSec libraries do support ID attributes. However, you have to
 301 tell LibXML2/XMLSec what is the name of <span style="font-weight: bold;">your </span>ID attribute. XML
 302 specification does not require ID attribute to have name "Id" or "id".
 303 It can be anything you want! <br></p>
 304 <br><code>Id</code><code>Data</code><blockquote><code> &lt;?xml version="1.0"
 305 encoding="UTF-8"&gt;<br>
 306 &lt;Root&gt;<br>
 307 &lt;Data Id="1234"&gt;<br>
 308 The data I want to sign<br>
 309 &lt;/Data&gt;<br>
 310 &lt;/Root&gt;<br></code></blockquote>
 311 <p>One can use a simple DTD: </p>
 312 <blockquote><code> &lt;!DOCTYPE test [<br>
 313 &lt;!ATTLIST Data Id ID #IMPLIED&gt;<br>
 314 ]&gt;<br></code></blockquote>
 315 <p> The DTD might be directly included in the XML file or
 316 located in a standalone file. In the second case, you might load the
 317 DTD in xmlsec command line utility with "--dtd-file" option. <br></p>
 318 <p>2) Use <a href="http://www.w3.org/TR/xml-id/">xml:id</a>.
 319 This is a new W3C Working Draft and not all XML parsers support it now
 320 (LibXML2 does!). <br></p>
 321 <p>3) Application can directly declare ID attribute to
 322 LibXML2/XMLSec. If you are using xmlsec command line utility see
 323 "--id-attr" option. If you are writing a C/C++ application
 324 yourself, call<code>xmlAddID</code> function.
 325 However, this approach might make you signature non-interoperable with
 326 other
 327 XMLDSig implementations.<br></p>
 328 <h4>
 329 <a name="section_3_3"></a>3.3.<span style="font-weight: bold;"> </span>I am trying to sign an
 330 XML document and I have a
 331 warning about "empty nodes set". Should I worry about this?</h4>
 332 <p> Most likely <b>yes</b>. When it's not an error from
 333 specification point of view, I can hardly imagine a real world case
 334 that requires signing an empty nodes set (i.e. signing an empty
 335 string). Most likely, you have this error because you are trying to use
 336 ID attribute and you do not provide a DTD for the document (see <a href="faq.html#section_3_2">section 3.2</a>
 337 about ID
 338 attributes).<br></p>
 339 <h4> </h4>
 340 <h4>
 341 <a name="section_3_4"></a>3.4. I am trying to
 342 sign/validate a document but
 343 xmlXPtrEval function can't evaluate "xpointer(id('XXXXXXX'))"
 344 expression. What's wrong?</h4>
 345 <p>First of all, read <a href="#section_3_2">section 3.2</a>
 346 about ID
 347 attributes.
 348 If you have tried to declare required ID attribute in DTD and
 349 you still have problems then I would guess that you are playing with
 350 Visa 3D protocol. This protocol tries to reference to an "id" attribute
 351 defined as CDATA instead of ID in the DTD (it is impossible in XML as
 352 described in <a href="#section_3_2">section 3.2</a>). Even worse, the
 353 value
 354 of this Visa 3D "id" attribute may start from number or contain "+" or
 355 "/" and this breakes <a href="http://www.w3.org/TR/REC-xml#sec-attribute-types">XML
 356 specification</a> again. Based on this, I have to say that Visa
 357 3D protocol does not use XML or XMLDSig specifications. And if you can
 358 then you should
 359 probably let Visa guys know about this problem (thought it was already
 360 done
 361 several times).</p>
 362 <p>The only good solution for this problem is changing Visa
 363 3D protocol.
 364 However,
 365 it might take time. As a short term solution you can use a special
 366 "Visa 3D
 367 hack" in xmlsec. Please note, that nobody (including me) knows what
 368 else
 369 might be broken in your application if you decide to use this hack. You
 370 are on
 371 your own here because this hack makes your application to work with
 372 non-XML
 373 and non-XMLDSig but some "Visa 3D" files. </p>
 374 <p>In order to process "Visa 3D" documents, you need to do
 375 two things: </p>
 376 <ul>
 377 <li>Register ID attributes manually (<code>xmlAddID</code>
 378 function or <code>--id-attr</code> option for xmlsec command line
 379 utility).</li>
 380               <li>Enable Visa 3D hack in XML DSig context (<code>dsigCtx-&gt;flags
 381 |= XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK</code> or <code>--enable-visa3d-hack</code>
 382 option for xmlsec command line utility).</li>
 383             </ul>
 384 <b>This is a hack</b><b>. You are warned!</b><br><p><b>UPDATE:</b> It appears that recent version (Novemeber, 2005)
 385 of Visa3D DTD does have this problem corrected and now "id" attribute
 386 is declared as ID. Just get the new DTD and everything should work
 387 without this hack.</p>
 388 <h4>
 389 <a name="section_3_5"></a>3.5. I have a document signed
 390 with a certificate that
 391 is now expired. Can I verify this signature?</h4>
 392 <p> Yes, you can. However, you need to be carefull. Most
 393 likely you do want to make sure that the certificate was not expired
 394 when the document was signed. The <a href="http://www.w3.org/Signature">XML
 395 Digital Signature</a> specification does not have a standard way to
 396 include the signature timestamp. Which means that you need to define
 397 where to put timestamp by yourself. Please note, that the timestamp <b>must</b>
 398 be signed along with the other data.<br>
 399 Finaly set the desired verification time in <code>certsVerificationTime</code>
 400 member of the <code>xmlSecKeyInfoCtx</code> structure. </p>
 401 <p> If you are using xmlsec command line utility then you
 402 can use <code>--verification-time &lt;time&gt;</code> option (where <code>&lt;time&gt;</code>
 403 is the local system time in the "<code>YYYY-MM-DD HH:MM:SS</code>"
 404 format). </p>
 405 <h4> <a name="section_3_6"></a>3.6. I really like the
 406 XMLSec
 407 library but it is based
 408 on OpenSSL and I have to use another crypto library in my application.
 409 Can you write code to support my crypto library?</h4>
 410 <p> The XMLSec library has a very modular structure and
 411 there should be no problem with using another crypto library. For
 412 example, XMLSec already supports <a href="http://www.mozilla.org/projects/security/pki/nss/">NSS</a>,
 413 MSCrypto API and <a href="http://www.gnu.org/software/gnutls/gnutls.html">GnuTLS</a>.
 414 Check the latest release and/or the mailing list and you might find
 415 that your library is already supported or someone working on it.<br>
 416 If you are not so lucky, then you can either write some code by
 417 yourself or contact me in private email to discuss possible options. </p>
 418 <h4> <a name="section_3_7"></a>3.7. I really like the
 419 XMLSec
 420 library but it does not
 421 have cipher or transform that I need. Can you write code for me?</h4>
 422 <p> The XMLSec library has a very modular structure and
 423 there should be easy to add any cipher or other transform. Again, you
 424 can either write some code by yourself or try to talk to me in private
 425 email. </p>
 426 </td></tr></table></td>
 427 </tr></table></body>
 428 </html>