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 use xmlsec with proprietary application or library? Can I use xmlsec with a GNU GPL application or library?
MIT license
XML Security Library module
|
Dependencies
|
Dependencies License
|
Using with proprietary
applications/libraries
|
Using with MIT/BSD applications/libraries
|
Using with GPL
applications/libraries
|
xmlsec-core
|
LibXML2/LibXSLT
|
MIT License |
Yes.
|
Yes.
|
Yes.
|
xmlsec-openssl (also requires
xmlsec-core library)
|
OpenSSL
|
OpenSSL License
|
Yes.
|
Yes. |
May be. OpenSSL FAQ
states that OpenSSL library is covered by a special
GPL exception thus it could be used in GPLed
applications/libraries. However, some people think that this is not
true (one
and two).
|
xmlsec-gnutls (also requires
xmlsec-core library) |
GnuTLS
|
GPL
|
Yes, but only if the application is not distributed.
|
Yes. |
Yes.
|
xmlsec-nss (also requires
xmlsec-core library) |
NSS
|
Dual licensing: Mozilla
Public License and GPL
|
Yes.
|
Yes. |
Probably yes, but at the time I
am writing this there are some unresolved
issues.
|
xmlsec-mscrypto (also requires
xmlsec-core library) |
MSCrypto API
|
Microsoft licensing: The
libraries are part of MS Windows, and are also distributed with
Internet Explorer.
|
Unknown.
|
Unknown. |
Unknown. |
xmlsec-mscrypto (also requires
xmlsec-core library) |
MSCrypto API
|
Microsoft licensing: The
libraries are part of MS Windows, and are also distributed with
Internet Explorer.
|
Unknown.
|
Unknown. |
Unknown. |
If you have questions about XML Security Library licensing then feel free to send these questions to the mailing list.
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 check
make install
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:
-
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.6. 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.7. 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>
]>
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. Also
xmlsec command line utility has "--id-attr" option that directly
registers given attribute in the document's ID attributes table.
However, this is a hack for Visa 3D protocol
and you should use DTD in all other cases.
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 am trying to sign/validate a document but xmlXPtrEval function
can't evaluate "xpointer(id('XXXXXXX'))" expression. What's wrong?
First of all, read section 3.2 about ID attributes.
If you have tried to declare required ID attribute in DTD and
you still have problems then I would guess that you are playing with
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 section 3.2). Even worse, the value
of this Visa 3D "id" attribute may start from number or contain "+" or "/"
and this breakes XML
specification/> again. Based on this, I have to say that Visa 3D protocol
does not use XML or XMLDSig specifications. And if you can then you should
probably let Visa guys know about this problem (thought it was already done
several times).
The only good solution for this problem is changing Visa 3D protocol. However,
it might take time. As a short term solution you can use a special "Visa 3D
hack" in xmlsec. Please note, that nobody (including me) knows what else
might be broken in your application if you decide to use this hack. You are on
your own here because this hack makes your application to work with non-XML
and non-XMLDSig but some "Visa 3D" files.
In order to process "Visa 3D" documents, you need to do two things:
- Register ID attributes manually (
xmlAddID function or
--id-attr option for xmlsec command line utility).
- Enable Visa 3D hack in XML DSig context (
dsigCtx->flags |= XMLSEC_DSIG_FLAGS_USE_VISA3D_HACK
or --enable-visa3d-hack option for xmlsec command line utility).
hackYou are warned!3.4. 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.5. 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.6. 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.
|