XML Security Library

LibXML2
LibXSLT
OpenSSL

XML Security Library 0.1.x
Design Overview


Aleksey Sanin <aleksey@aleksey.com>
March 3 2002

0.  Design goals.

The XML Security Library 0.0.X was designed with a goal to provide high performance implementation of the XML Digital Signature and XML Encryption specifications. It was limited to OpenSSL crypto engine but it quickly turns out that changing crypto engine for XML Security Library users is very difficult. There are many political and technical reasons why particular crypto engine could not be used in particular organization. The "OpenSSL and only OpenSSL" restriction was a serious limitation for the library and the major goal of the new XML Security Library 0.1.X series is to provide an easy way to use integration with crypto engine. Of course, performance is still a P0 requirement.

1. Processing model.

XML Security Library performs signature or encryption by processing input xml or binary data and a template that specifies a signature or encryption skeleton: the transforms, algorithms, the key selection process. A template has the same structure as the desired result but some of the nodes are empty. XML Security Library gets the key for signature/encryption from keys managers using the information from the template, does necessary computations and puts the results in the template. Signature or encryption context controls the whole process and stores the required temporary data.


Signature/encryption processing model

Since the template is just an XML file, it might be created in advance and saved in a file. It's also possible for application to create templates without using XML Security Library functions. Also in some cases template should be inserted in the signed or encrypted data (for example, if you want to create an enveloped or enveloping signature).
Signature verification and data decryption do not require template because all the necessary information is provided in the signed or encrypted document:

Verification/decryption processing model

2. Library structure and dependencies.

In order to provide the an ability to use different crypto engines, the XML Security Library was splitted in two parts: core library (xmlsec) and crypto library (xmlsec-openssl, xmlsec-gnutls, xmlsec-nss, ...). The library dependencies are shown on Figure 1. The core library has no dependency on any crypto library and provides implementation of all the engines as well as support for all the non crypto transforms (xml parser, c14n transforms, xpath and xslt transforms,...). The XML Security Crypto library provides implementations for crypto transforms, crypto keys data and key data stores. Application is linked with particular XML Security Crypto library (or even libraries). But the actual application code might be general enough so switching crypto engine would be a matter of changing several #include directives.
Internal XML Security Library structure and dependencies between objects are shown on  Figure 2 and Figure 3.

2. Transforms.

XML Digital Signature and XML Encryption standards are very flexible and provide an XML developer many different ways to sign or encrypt any part (or even parts) of an XML document. The key for such great flexibility is the transforms model defined by these specifications. Specifications define transform as a method of pre-processing binary or XML data before digest or signature calculation/verification. XML Security Library extends this definition and names "transform" any operation performed on the data: reading data from an URI, xml parsing, xml transformation, calculation digest, encrypting or decrypting. Each transform provides at least one of the following callbacks: "push binary data", "push xml data", "pop binary data" or "pop xml data":


Transform


In order to simplify transforms development, additional "execute" callback was added. This callback updates internal transform buffers and is used by the "default" xml/binary push and pop callbacks. For example, most of the crypto transforms could be implemented by just implementing one "execute" callback. However, in some cases using push/pop callbacks is more efficient.
When necessary, XML Security Library constructs a transforms chain as specified in the template or document and processes data by "pushing" or "popping" through the chain. For example, then binary data chunk is pushed through a binary-to-binary transform, it processes this chunk and pushes the result to the next transform in the chain. The Figure 4 shows an example transforms chain constructed for <dsig:Reference/> element processing.
The XML Security library transforms engine makes sure that output data type (binary or xml) of previous transform matches the input data type of the next transform by inserting XML parser or default C14N when necessary. Custom transforms could be added by the crypto plugin or application at any time.

3. Keys and keys data. 

A key in XML Security Library is a representation of the <dsig:KeyInfo/> element and consist of several key data objects. The "value" key data usually contains raw key material (or handlers to key material) required to execute particular crypto transform. Other key data objects may contain any additional information about the key. All the key data objects in the key are associated with the same key material. For example, if a DSA key material has both an X509 certificate and a PGP data associated with it then such a key can have a DSA key "value" and two key data objects for X509 certificate and PGP key data.


Key

 
XML Security Library has several "invisible" key data classes. These classes never show up in the keys data list of a key but are used for <dsig:KeyInfo/> children processing (<dsig:KeyName/>, <dsig:EncryptedKey/>, ...). As with transforms, application might add any new key data objects or replace the default ones.

4. Keys manager and keys data stores.

Processing some of the key data objects require additional information which is global across the application (or in the particular area of the application). For example, X509 certificates processing require a common list of trusted certificates to be available. XML Security Library keeps all the common information for key data processing in a a collection of key data stores called "keys manager":


Keys Manager


Keys manager has a special "keys store" which lists the keys known to the application. This "keys store" is used by XML Security Library to lookup keys by name, type and crypto algorithm (for example, during <dsig:KeyName/> processing). The XML Security Library provides default "flat list" based implementation of a simple keys store. The application can replace it with any other keys store (for example, based on an SQL database).
Keys manager is the only object in XML Security Library which is supposed to be shared by many different operations. Usually keys manager is initialized once at the application startup and later is used by XML Security library routines in "read-only" mode. If application or crypto functions need to modify any of the key data stores inside keys manager then proper synchronization must be implemented. In the same time, application can create a new keys manager each time it needs to perform XML signature, verification, encryption or decryption.

5. Data processing contexts.

Application may control XML Security Library engines behavior using several context objects. New context objects are created for each operation and could not be reused. XML Security Library also uses context objects to store temporary data and return additional information to the application.




Aleksey Sanin