The OpenOffice.org Document Signatures

Version 1.1, April 2005

Michael Mi

Malte Timmermann

Table of Contents

1. Introduction	3

2. Classes Involved	4

2.1 Component Implementation	4

2.1.1 DocumentDigitalSignatures	4

2.2 Helper classes	4

2.2.1 XMLSignatureHelper	4

2.2.2 XSecControler	5

2.2.3 XSecParser	5

2.2.4 DocumentSignatureHelper	5

2.2.5 UriBindingHelper	5

2.2.6 ImplXMLSignatureListener	5

2.3 Framework	6

2.3.1 SAXEventKeeper	6

2.3.2 XMLDocumentWrapper	6

2.3.3 Encryptor	6

2.3.4 Decryptor	6

2.3.5 SignatureCreator	6

2.3.6 SignatureVerifier	6

2.4 XMLSec Bridge	6

2.4.1 XMLSecurityContext	6

2.4.2 SecurityEnvironment	7

2.4.3 SEInitializer	7

2.4.4 X509Certificate	7

2.4.5 XMLEncryption	7

2.4.6 XMLSignature	7

3. Use Cases	8

3.1 Generate a signature	8

3.1.1 Prepare the environment	8

3.1.2 Configure the signature	8

3.1.3 Generate the signature	8

3.1.4 Check the status	8

3.2 Verify a signature	8

3.2.1 Prepare the environment	8

3.2.2 Verify the signature stream	9

3.2.3 Check the status	9

Introduction

It quite complicated to sign only parts of documents.

If you only sign a certain part of the document, but not all underlying style sheets, some information can easily be hidden by manipulating the style sheets, without breaking the signature.

For this reason, OpenOffice.org only supports signing the complete content right now.

Complete content means that binary and XML streams are signed completely, is doesn't mean that all streams in the document (zip files) are signed. There are different modes to sign only the macros or only the 'real' document content.

This way, we can provide a separate component which is able to create and verify signatures base on a given document, there is no need to change any code for this in the application or filter code.

Information about the used “XML Security Framework” can be found in XMLSecurityFramework.sxw.

Classes Involved

Component Implementation

DocumentDigitalSignatures

Provides application level functions for the digital signature feature.

Implementation of XdocumentDigitalSignatures.

These functions include:

sign the content of the document;

verify document content's signatures;

show document content's signatures;

sign the content of the marco;

verify marco's signatures;

show marco's signatures;

sign the whole packages;

verify package's signatures;

show package's signatures;

show information of a particular certificate;

manage trusted sources;

check whether an author is trusted or not;

check whether a location is trusted or not;

add an author to trusted sources;

add a location to trusted source.

Helper classes

XMLSignatureHelper

Provides high level APIs for the digital signature feature, including:

choose security environment;
a system can include more than one security environment.
For example, in NSS, a user can have a software key store, a smartcard, etc. Each of them is a security environment.
Before generate a signature, a security environment must be chosen for the underlying engine to use.

URI binding management;
a URI binding is a connection between a URI and a stream.
Either creating signature or verifying signature, when dealing with a external URI reference, its corresponding stream should be read as the data source.

mission management;
a mission means a independent job for the xml security framework.
When a mission starts, the xml security framework will initialize all resources, including all xml security components, all URI binding information, etc.
When a mission ends, all resources related with this mission will be released.

storage management;
set the storage which should be used by the default URI binding. When a URI is not explicitly binded with a storage, the default storage is used.

security identifier management;
every signature inside the xml security framework has its identifier(ID). The ID is widely used by many APIs.

listener management;
because the signing/verifying operation is asynchronous, a listener is used to receive the result of signing/verifying operation for a particular signature.

generate signatures;

verify signatures.

XSecControler

The XSecController controls the xml security framework. Its responsibilities include:

generate security identifier;

mission control;

manipulate the SAX chain;
xml reading and writing in SO is SAX based. A SAX chain means the sequence of component through which SAX event stream passes.
During creating/verifying signatures, the normal SAX event stream needs to be intervened: some data will be buffered, some data will be changed, and some new data will be inserted.
To fulfill these features, new component need to be inserted into/then removed from the SAX chain at proper time, the XSecController is in charge of this job.

configure a new signature;
to create a signature, many attributes should be configured, including its reference URIs, the key to use, the time stamp, etc;

generate a new signature;

verify a signature;

manage signature information.
Either creating signature or verifying signature, the XSecController will reserve information for all signatures it handled, then these information can be used by other components.

XSecParser

When verify a document, an XSecParser is inserted into the SAX chain to detect signature related contents.

when a Signature element reaches the XSecParser, the XSecParser will inform the XSecController that a new signature is detected. After that, the XSecParser also collect more information, such as reference URI, reference transform algorithm, reference digest value, signature value, issuer name, serial number, etc.

when an element with an ID attribute reaches the XSecParser, the XSecparser will also inform the XSecController, then the XSecController will check whether this element is signed by any detected signature.

DocumentSignatureHelper

A utility to handle a particular storage, two functions are supported:

get signature stream from a storage;

get element list from a storage.

UriBindingHelper

A utility to manage the binding list between URIs and streams, two functions are supported:

set stream binding for a particular URI.

get stream binding for a particular URI.

ImplXMLSignatureListener

A utility providing functions of all kind of listener. When using this helper, the caller need to configure callback for each listener, then when a listener receives a message, the corresponding callback function will be called. Functions include:

when reading document, detect signature element from the input stream;

monitor the signature generation result;

monitor the signature verification result.

Framework

The following classes from the XML Security Framework are used.

For more information about the framework see XMLSecurityFramework.sxw

SAXEventKeeper

Buffers security related SAX events, which in turn will be used in signature generation, signature verification, encryption and decryption.

For more information, see SAXEventKeeper.

XMLDocumentWrapper

Transforms data between SAX format and DOM format.

For more information, see XMLDocumentWrapper.

Encryptor

Collects related data and launches the encryption operation.

For more information, see Encryptor.

Decryptor

Collects related data and launches the decryption operation.

For more information, see Decryptor.

SignatureCreator

Collects related data and launches the signature generation operation.

For more information, see SignatureCreator.

SignatureVerifier

Collects related data and launches the signature verification operation.

For more information, see SignatureVerifier.

XMLSec Bridge

For some of the implementations modules from the open source projects “libxmlsec” and “libxml2” are used.

XMLSecurityContext

Manages a security context. Currently, two security contexts are supported, MSCrypto and NSS.

A security context manages a group of security environment. In NSS, each module is a security environment; in MSCrtpro, because it is a single-module infrastructure, so only one security environment exists in the security context.

Functions include:

add a security environment;

get a particular security environment by its index;

configure the default security environment;

get the default security environment.

SecurityEnvironment

Manages information in a security environment, functions include:

get all personal certificates in this security environment;

search a particular certificate according issuer name and serial number;

build a certificate path;

create a certificate from raw data;

create a certificate from ASCII data;

verify a certificate;

get certificate characters.

SEInitializer

Create, initialize and destroy security context along with its security environments.

X509Certificate

Provides information about a particular certificate. Those information includes:

version;

serial number;

issuer name;

subject name;

period of validity;

issuer id;

subject id;

extension;

raw data of the certificate;

public key algorithm;

public key value;

SHA1 thumbprint;

MD5 thumbprint;

key usage.

XMLEncryption

The underlying engine to implement the encryption/decryption operation.

For more information, see XMLEncryption.

XMLSignature

The underlying engine to implement the signature generation/verification operation.

For more information, see XMLSignature.

Use Cases

Generate a signature

Prepare the environment

Create a XMLSignatuerHelper, which creates a XSecController internally.

The XMLSignatureHelper initializes a security context. On Windows the users key store is used, on other platforms the default Mozilla profile is detected.

Asks the XMLSignatureHelper to start a new mission. During the starting process, the XMLSignatureHelper creates a UriBindingHelper internally, the UriBindingHelper will be used to get a stream according to a URI.

Selects a security environment from the XMLSignatureHelper.

Selects a certificate from the security environment. This certificate along with its corresponding private key is used to generate the signature.

For each signature, The XMLSignatureHelper needs to have a unique identifier. So a new security id is required from the XMLSignatureHelper.

To save the signature, an output stream is created.

Configure the signature

Configures the certificate.

Configures the date and time.

Configures each stream which the signature will sign.

All above steps need the security id as the identifier of the signature.

Generate the signature

Provides the output stream to the XMLSignatureHelper, and asks the XMLSignatureHelper to generate the signature.
Inside the XMLSignatureHelper, the following things are done:
1. creates a document handler on the output stream, then the XMLSignatureHelper exports all necessary SAX events (such as the startDocument event) before the signature element;
2. asks the XSecController to write the signature element;
3. the XSecController creates a SAXWrite on the document handler, and setups the SAX chain.
Then the signature generation process begins, for more information about this step, refer to sign detached content.
Here the XSecController acts as the XMLExporter.
4. exports all necessary SAX events (such as the endDocument event) behind the signature element.

Asks the XMLSignatureHelper to end the mission. During this step, all configuration information are reset.

Check the status

the user can get signature information from the XMLSignatureHelper to check whether the signature is generated successfully.

Verify a signature

Prepare the environment

Creates an XMLSignatuerHelper, which creates a XSecController internally.

The XMLSignatureHelper initializes a security context. On Windows the users key store is used, on other platforms the default Mozilla profile is detected.

Provides the XMLSignatureHelper a user defined signature-verify handler.
The signature-verify handler will decide whether to verify a signature or not when encounter a signature element in the SAX event stream.

Asks the XMLSignatureHelper to start a new mission.
During the starting process, the XMLSignatureHelper creates a UriBindingHelper internally, the UriBindingHelper will be used to get a stream according to a URI.

Opens the signature input stream.

Verify the signature stream

Provides the input stream to the XMLSignatureHelper, and asks the XMLSignatureHelper to verify it.
Inside the XMLSignatureHelper, the following things are done:
1. creates a SignatureListener, which internally uses the signature-verify handler to decide whether a signature element should be verified or not.
2. creates a XSecParser, which is used to collect information for to-be-verified signature element;
3. setups the SAX chain in the following sequence: the SignatureListener, the XSecParser and the XSecController. In this way, a signature element will reach the SignatureListener first, the SignatureListener will call the signature-verify handler to decide whether this signature should be verified, if so, the XSecController will be notified and will ask the XSecParser to collect information for this signature;
4. parses and verify the signature stream. For more information about this step, refer to verify detached signature. Here the XSecController acts as the XMLImporter.
5. after the stream is verified, release all related resources.

Closes the input stream.

Asks the XMLSignatureHelper to end the mission. During this step, all configuration information are reset.

Check the status

To check the validity of signature, the user can get signature information from the XMLSignatureHelper.

The workflow can be found in OpenDocumentSignatures-Workflow.sxd

Use Cases	9/9

1995-11-21T17:41:00

Malte Timmermann