Apache Santuario

Frequently Asked Questions - Apache XML Security for C++

After discussion with the Santuario PMC, it has been decided to address the long term lack of support for the C++ library by formally retiring the code here at Apache. The Java code of course remains well supported and will continue to be developed.

As of now, the C++ code is frozen here. The current sole maintainer will be transferring the source code to the Shibboleth Project and it will be maintained by that team for some period of time because it is a dependency of that software, but it will not be supported for any third-party use. It is estimated that the code will be fully retired some time before 2030. The code will be publically hosted and accessible after the transition, and the license is not changing.

Once the code transition occurs, which may not be for some time yet, we will update more of the site as is appropriate to reflect the transition. In the event a significant issue arises with the library prior to the transition, we will endeavor to address it here.

Compiling and Requirements

What are the significant changes with V2.0.0?

The API has been slightly updated and a variety of deprecated methods have been removed, along with many public references to an older set of enumeration constants for algorithms of various sorts. The public APIs are now primarily URI-based such that future algorithm additions should not require public changes. So most code will be slightly broken but should require minimal modification to be updated.

There are significant changes to the support status of parts of the library that lack maintainers. The following features are deprecated at present and at risk of future removal:

  • NSS support
  • WinCAPI support
  • XKMS features

All those features can be left out of the build to ensure no usage of them by downstream projects wishing to limit their security exposure and this is advisable.

Finally, the set of platforms formally supported by the maintainer of the library is limited, and no longer includes Solaris. Most releases of the library will likely build on most platforms, including Solaris, but likely with patches required that will be happily accepted by the project. The formal set of platforms supported is exactly the set supported by the Shibboleth Project, whose resources are the sum total actively maintaining this code.

Is OpenSSL required?

While Windows Crypto API and NSS interfaces are also provided, they are moribund, lack modern algorithm support, and are deprecated at present.

It is possible to implement interfaces for other cryptographic libraries and pass them into the xml-security-c library during initialisation (via the XSECPlatformUtils::Initialise() call).

TL;DR, yes, OpenSSL is required.

Does the library provide a full C++ wrapper for OpenSSL?

No. The C++ crypto interface layer provided for the library provides only the subset of cryptographic functions necessary for the library to make calls to the provided library. Applications will need to work directly with OpenSSL (or other libraries) to read and manipulate encryption keys that should then be wrapped in XSECCrypto* objects and passed into the library. There have been additions to the API over time to make the primitives in this library more usable as mechanisms for general operations, but they are not complete.

Is Xerces required?

Yes, and the library now requires V3.2.0 or above. No older versions of Xerces are supported so any such use is highly ill-advised in any event.

Is Xalan required?

The library can be compiled without linking to Xalan. However doing so will disable support for XPath and XSLT transformations. If used, only the very latest Xalan release, 1.0.11, will successfully build with Xerces 3.2 and this library.

Library Use

I sign a document and when I try to verify using the same key, it fails

After you have created the XMLSignature object, before you sign the document, you must embed the signature element in the owning document (which is returned by the call to DSIGSignature::createBlankSignature(...)) before calling the DSIGSignature::sign() method,

During canonicalisation of the SignedInfo element, the library looks at the parent and ancestor nodes of the Signature element to find any namespaces that the SignedInfo node has inherited. Any that are found are embedded in the canonical form of the SignedInfo. (This is not true when Exclusive Canonicalisation is used, but it is still good practice to insert the element node prior to the sign() method being called).

If you have not embedded the signature node in the document, it will not have any parent or ancestor nodes, so it will not inherit their namespaces. If you then embed it in the document and call verify(), the namespaces will be found and the canonical form of SignedInfo will be different to that generated during sign().

How does the library identify Id attributes?

During a signing operation, finding the correct Id attribute is vital. Should the wrong Id Attribute be used, the wrong part of the document will be identified, and what the user signs will not be what they expect to sign.

The preferred method (and the method the library uses first) of finding an Id is via the DOM Level 2 call DOMDocument::getElementById(). This indicates to the library that the Id has been explicitly identified via a schema, DTD or during document building. However, if this call fails, the library will then search the document for attributes named "Id" or "id" with the appropriate value. The first one found will be used as document fragment identifier.

As of version 1.2, the library also provides methods to allow callers to set additional Id attribute names. This can be done in one of two ways. DSIGSignature::registerIdAttributeName() will register a new name that will not be matched to a namespace. DSIGDSignature::registerIdAttribiteNameNS() will register an attribute name together with the namespace in which the attribute resides.

As this is a potential security exposure, this behaviour can be disabled using a call to DISGSignatures::setIdByAttributeName(false). There are also methods provided to modify the list of attributes that will be searched. However it is recommended that these methods not be used, and DOM attributes of Type=ID be used.

Warning In version 1.1 and above, the library defaults to searching for Id attributes by name if a search by Id fails. As this is a potential security risk, this behaviour may be changed in a future version of the library.

What parts of the XKMS specification does the library support?

The library currently supports X-KISS (XML Key Information Service Specification) message generation and processing. XKMS support is optional with V2.0.0 and can be omitted from the build.

The XKMS support is deprecated.

Does the library provide a programmatic XKMS client?

A command line tool xklient is provided for generating and processing messages. This can be used as an example for processing XKMS messages.

  • No labels