XML Security Library 0.1.x
Design Overview
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.

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:
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":
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.
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 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.
|