XML Security Library: Documentation

Home Download News Documentation FAQ Tutorial API reference Examples XML Digital Signature Online Verifier XML Encryption XML Canonicalization Reporting Bugs Mailing list Related
# Frequently Asked Questions ### 0. Why have you wrote xmlsec? Very simple: when I decided to understand the XML Digital Signature and XML Encrytpion 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. ### 1. License(s). #### 1.1. Licensing Terms for xmlsec. XML Security Library is released under the MIT License, see the file Copyright in the distribution for the precise wording. #### 1.2. Can I embed xmlsec in a proprietary application ? Yes. The MIT License allows you to also keep proprietary the changes you made to xmlsec, but it would be graceful to provide back bug fixes and improvements as patches for possible incorporation in the main development tree. Probably you should also check OpenSSL and LibXML2 licenses as well. #### 1.3. Can I use xmlsec with a GNU GPL library? Yes. MIT license is compatible with GNU GPL library. However, xmlsec is based on OpenSSL and OpenSSL license is not compatible with GNU GPL. In most cases, this should not cause any problems because of a special exception in the GPL (also check what OpenSSL FAQ says about this). ### 2. Installation. #### 2.1. Where can I get xmlsec? The original distribution comes from XML Security Library page. Also xmlsec is available from rpmfind.net miror. #### 2.2. How to compile xmlsec? On Unix just follow the "standard": `gunzip -c xmlsec-xxx.tar.gz | tar xvf -` `cd xmlsec-xxxx` `./configure --help` `./configure [possible options]` `make` `make install` `make check` At that point you may have to rerun ldconfig or similar utility to update your list of installed shared libs. On Windows the process is more complicated. Please check readme file in `xmlsec-xxxx/win32` folder. #### 2.3. What other libraries are needed to compile/install xmlsec? The XML Security Library requires: LibXML LibXSLT (optional) OpenSSL version 0.9.7 (prefered) or version 0.9.6. GnuTLS and Libgcrypt - GNU SSL and cryptographic libraries. NSS - Mozilla cryptographic library. #### 2.4. Why does make check fail for some tests? First of all, some tests must fail! Please read the messages printed before the tests. 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. if this does not help then probably there is a bug in the xmlsec or in the xmlsec tests. Please submit the bug report and I'll try to fix it. #### 2.5. I get the xmlsec sources from CVS and there is no configure script. Where can I get it? The configure (and other Makefiles) are generated. Use the `autogen.sh` script to regenerate the configure and Makefiles, like: `./autogen.sh --prefix=/usr` #### 2.5. I do not need all these features supported by xmlsec. Can I disable some of them? Yes, you can. Please run `./configure --help` for the list of possible configuration options. #### 2.6. I am compiling XMLSec library on Windows and it does not compile (crashes right after the launch). Can you help me? 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. 1) Incorrect MS C runtime libraries. 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. If you downloaded XMLSec, LibXML, LibXSLT and OpenSSL binaries from Igor's page 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. 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. 2) Static linking without correct defines. When people link statically to XMLSec, then they must `#define XMLSEC_STATIC` 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. 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 `#define LIBXML_STATIC #define LIBXSLT_STATIC #define XMLSEC_STATIC` 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 `__declspec(dllimport)` prepended and that will give headaches if static LibXML is used for linking. This scheme makes it possible to have any combination of static and dynamic libraries in the resulting executable. Its cost is the need to `#define` apropriate macros. People would ideally define them by using the compiler's `/D` switch in projects that link statically. ### 3. Developing with XMLSec. #### 3.1. xmlSecDSigCtxValidate() function returned 0. Does this mean that the signature is valid? No! Function xmlSecDSigCtxValidate() returns 0 when there were no processing 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 and the `status` member of the `xmlSecDSigCtx` structure is equal to `xmlSecDSigStatusSucceeded`. #### 3.2. I am trying to sign an XML document and I have a warning about "empty nodes set". Should I worry about this? Most likely yes. 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: `<?xml version="1.0" encoding="UTF-8"> <Root> <Data Id="1234"> The data I want to sign </Data> <Signature xmlns="http://www.w3.org/2000/09/xmldsig#"> ... <Reference URI="#1234"> ... </Reference> ... </Signature> </Root>` always results in an empty nodes set (and an empty string signed!) unless you have a DTD that declares `Id` attribute of the `Data` element to be an ID attribute: `<!DOCTYPE test [ <!ATTLIST Data Id ID #IMPLIED> ]>` 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 `xmlAddID` function. However, this might make you signature non-interoperable with other XMLDSig implementations. #### 3.3. I have a document signed with a certificate that is now expired. Can I verify this signature? 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 XML Digital Signature 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 must be signed along with the other data. Finaly set the desired verification time in `certsVerificationTime` member of the `xmlSecKeyInfoCtx` structure. If you are using xmlsec command line utility then you can use `--verification-time <time>` option (where `<time>` is the local system time in the "`YYYY-MM-DD HH:MM:SS`" format). #### 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? 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 and GnuTLS. Check the latest release and/or the mailing list and you might find that your library is already supported or someone working on it. 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. #### 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? 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.
Aleksey Sanin