Improving The Digital Signature Feature

From Apache OpenOffice Wiki
Jump to: navigation, search


Digital signatures on documents can be very useful. What may prevent people from using them are

  • complicated usage
  • unclear legal status

The first could be solved by a better implementation. For example, for non-Windows user it is quite complicated to maintain their private keys and certificates, because (OOo) does not use a system provided key store. Instead the key store of the default profile of Mozilla/SeaMonkey, Firefox or Thunderbird is used. There is no indication or preferences setting as to what key store is to be used.

The second issue is the more complicated one. Different countries and companies may have different requirements for digital signatures. These may affect the type of signatures, such as XML digital signature or Cryptographic Message Syntax (CMS), and used algorithms (hash algorithms, signature algorithms, signature / certificate validation algorithms.) Particularly the validation aspect can be very tricky. Because of the complexity of the validation algorithms and the lack of an legally accepted international standard, it is likely that the signature that complies with legal regulations in country A cannot be used in country B. Therefore it is necessary to provide solutions which are adapted to local requirements.

However, even if a product claimed to comply to those regulations, it would still be a risk to use the signatures unless it becomes certified by some legally accepted organization. For example, a company would not replace paper-written sales contracts by electronic documents because it could turn out later that some flaw in the signature implementation renders all signatures invalid. On the other hand a certified product can give some sort of assurance and help to promote the use of signatures.

Providing a certified signature implementation which can be used everywhere is a huge task and possibly not practical. Certification will certainly cost money and time and it may be necessary to repeat the certification process for every new release of OOo. Therefore the particular implementations and certification should be provided by interested parties.

The signature framework proposed in this document aims at making it easier for them to provide signature components for OOo. But it shall also enable users to easily configure different signature components which are installed in OOo. Those signature components will be distributed as extensions and can therefore be updated independent of OOo.


Signature Component
Consists of code and data needed to create and verify a digital signature applied to an ODF document. It is delivered as extension.
Signature Component Service Provider (SCSP)
The SCSP is a service which manages the installed signature components and makes it easier to develop them.
Every signature component provides this data file which contains information, such as menu items, status bar icons, etc., which are processed by Signature Component Service Provider.

Trusting the signature component

Users must be aware that they cannot trust that their documents are correctly signed and that signed documents are correctly validated unless they use a trusted environment and a trusted OOo and a trusted signature component. This is ALL needed to prevent that the processing of signatures is manipulated. So what does this all mean:

Trusted environment
Users should never have root / administrator rights to prevent virus infections. Accounts, particularly those of administrators, must be password protected.
Trusted OOo
Users must make sure to obtain the installation set from a trusted source. That is, the program should be signed, when it is provided through a physical devise, such as a DVD, memory card, etc. When downloading OOo, then this should happen through a secure connection from a trusted website (using https).
The same care must be taken when obtaining extensions. A malicious extension can contain services which override any services, including the SCSP, which are involved in signing/validating/displaying signatures and manipulates these processes. Unfortunately OOo cannot deal with signed extensions yet. But users could insist on downloading extensions only from a trusted website. That is, extensions should be downloaded using https. If they are delivered on a physical device (CD, DVD, memory card) then they should be signed.
Trusted signature component
Signature components are provided as extensions. Hence the same precautions apply. Additionally they should be certified so that users can be sure about the legal aspects of the signatures which they create.

The following scenario shows how a user could be deceived:

Some criminal downloads the source code of OOo and manipulates it so that all signatures created by himself are displayed as valid. He then builds OOo and sets up a web site from where it can be downloaded. People who install it can then be tricked to believe that documents signed by that criminal are trusted. Even worse, the criminal could impersonate others. That is, he would sign a document with his own private key and the modified OOo would recognize this signature and display a different person as signer.

Types of signatures

There are a lot of ways to sign a file. At the bottom there are different asynchronous cryptographic algorithms (RSA, DSA, Elgamal, etc.) and hash functions. These are typically enriched with additional information for the verification of the authenticity of the signer in the form of public key certificates (X.509v2, X.509v3, OpenPGP, etc.).

Signatures and certificates need to be "packaged" in a defined way. These packages may also contain or reference the signed data. For example, for XML data there are the standards XML Digital Signature and XAdES and for binary data there are CMS and CAdES (and probably other). These standards provide different ways of how the signed data is referenced or contained. The signatures (together with certificates, etc.) can be contained in separate files or combined in one file.

The digital signature used by OOo actually uses a "detached" signature. That is, the signature and the signed files are separate. However, they are then all put together into one zip file. The advantage of a contained signature is that one doesn't needs to keep track of the additional signature file(s) when copying or moving the document. That is, that in case there is a "real" detached signature, it could make sense to attach it to the document again and hence create a single file. This, however, is not to be confused with a document containing a signature.

OOo currently provides a signature for macros and the whole document (but not for the file as a whole.) One could also think about signing particular paragraphs in a document, or even particular cells in a spreadsheet. That is there could be variable number of signatures for one document.

With all these possibilities in mind it becomes clear, that there can be a wide variety of implementations. The signature framework should therefore be very flexible as to support as many implementations as possible.

Using different types of signatures

The signature framework of OOo should allow the installation of several signature components. This would theoretically allow to sign the same document using different signature components which could create conflicts because one type of signature could influence the other. One must also assume that a particular signature component is unaware of the signatures created by other signature components. This increases the danger of damaging or invalidating existing signatures.

For example, there are two signature components A and B. A creates the conventional XML Digital Signature and B creates a detached CMS signature for the entire document file. When B is applied before A, then B's signature will be invalid. That is, writing the signature within the document file (A), like any other modification of the files contents, breaks signature B.

Even if different signatures (over the same content) does not influence each other, they could still check differently (assuming we regard a signature as invalid when the certificate cannot be validated). This can be the case when the certificate validation routines are different, or signatures use different signature policies (XAdES, CAdES). To represent the validation results to the user in an understandable way would probably be a difficult task. One must also keep in mind that many users have only a very basic knowledge about digital signatures.

Because of these problems it seems best to only use one signature type. That is, OOo must prevent that a users signs the document when it was already signed using a different signature type (see 'Signature meta data').

Signature meta data

The signature meta data is contained in a new stream in the ODF document. It provides additional information about the signature. It is used to:

A signature component must always write the meta data when it creates a signature.

Qualifying signature information

This information is part of the signature meta data and the SignatureComponent.xcu (see 'The signature component'). It is a means to identify the active signature component and provides information about the used algorithms and standards. The latter is used by the signature framework in case that no active signature component could be determined and to display information in the options dialog.

The qualifying signature information allows OOo to determine the active signature component without executing the installed signature components.

The qualifying signature information need to contain sufficient information to uniquely identify a signature component which has the same capabilities as the signature component which created the signature (see 'The signature component'). For example, a user loads a document containing a signature which was produced by signature component A. When the signature was created, then the signature was valid. The user does not have signature component A but he has signature component B which claims to have the same capabilities as A. Then the user expects that the validation of the signature with B will show the same result as the validation with A.

The following information are therefore necessary:

  • publisher information
  • standard/specification of the signature
  • additional standards/specification
  • particular settings

For example:

<publisher>My Company Inc.</publisher>
  <name>W3C XMLDSIG</name>
  <required-optional-part>feature abc</required-optional-part>
<additional-spec>ODF 1.2</additional-spec>; 

The signature component

The signature component must make sure that all operations are performed according to the specifications as stated in the qualifying signature information which it provides.

A signature component can be 'self contained'. That is, it provides all functionality by itself, including all dialogs, and does not use any functionality provided by OOo. This way, the component could obtain a certification without the need to certify OOo as well. One advantage is that the same signature component can be installed in different versions of OOo without requiring to have all these versions of OOo being certified. This is the more important since the certification process is time comsuming and costly.

Even if a signature component is self contained, it should communicate the results of its operations to the caller. This would allow OOo to disable Macros, for example, when the macro signature is broken.

The active signature component

The signature component, which performs signature operations, such as creating, verifying, removing, etc., at a given time, will be called the active signature component. It is called active because there can be several signature components installed, but only the active one may perform signature operations. There can be only one active signature component at a time. If no signature component is installed, then there is no active signature component. The following scenarios show how the active signature component is selected.

  • Backing window
There is no active signature component.
  • New document or loaded unsigned document
The signature component selected in the options dialog is the active signature component.
  • Signed document (loaded signed document or a new document which was signed)
The active signature component is determined according to the algorithm in paragraph 'Using meta data to determine the active signature component'. There may be no active signature component.

When the user selects a different signature component in the options dialog, while no or one document is opened, then the following applies:

  • Backing window
Still no active signature component
  • Loaded unsigned document
The now selected signature component is active
  • Signed document
The active signature component is determined according to the algorithm in paragraph 'Using meta data to determine the active signature component'. There may be no active signature component.

The active signature need not be the same as the one the user selected in the options dialog. This is exactly then the case, when

  • a document contains a signature and there is no suitable signature component installed.
  • a document contains a signature but the respective signature component is not currently selected. This may happen, when one loads a signed document or when one just signed a document and then selects a different signature component in the options dialog.

If there is no active signature component and a signed document is opened, then no signature related operations can be performed. As a consequence the document must be in read-only state. The reason is, that any modification can invalidate a signature (or signatures) in which case it (they) must be removed. But only a suitable signature component, which would be the active signature component, knows how to do this. This also demonstrates how important it is to recognize that a document is signed. Because we do not know how the signatures look like and where they are located (could be a detached signature), we need a well known place were this information is contained. An this is the signature meta data.

Using meta data to determine the active signature component

The qualifying signature information contained in the document is to be compared with those of all installed signature components. There can be

no matching signature components
There will be no active signature component.
one matching signature component
This will be the active signature component.
two or more matching signature components
In this case also the publisher information is compared. The signature component which matches also the publisher information will be the active signature. Because the publisher information contains the extension identifier,there can be only only matching signature component. It is not possible to use two extensions with the same identifier at the same time.

Using the publisher information is important if there are two signature components which have the same signature specification. One must assume that signature components provide their own options page where one can modify the signature creation and validation. That is, the validation results of both components for the same signature can be different. Now let's assume that the publisher information is not used. The user installs both components and selects the second as the preferred one in the options dialog. Then he/she signs the document, which is then again validated. The validation operation obtains the active signature component, which will be the first one. However, this component has different options settings and therefore, the validation result can be invalid. In other words, a user signs the document and afterward when he /she checks the signature, then it could be displayed as invalid.

Invoking a signature component

To use the signature components it shall not be required to know the details of the actual signature components and the signatures of the document. A client will simply use the SCSP to obtain an interface for the active signature component. This interface shall be same for all signature components. Otherwise the client would still need to know details about particular signature components or the signatures contained in the document. This means that the client will only receive general validation results from the signature component. Based on this information the client can decide as to how to proceed with this document. For example it may decide to not show the document at all, disable various features (for example, macros) and warn the user. However, the signature component may have already informed the user about the validation result. In this case it is unnecessary that the client displays this information again. The client can obtain the information, if the signatures component displays itself the validation results, from the SCSP. The SCSP in turn obtains this information from the SignatureComponent.xcu.

Option pages for signature components

Users can use an options page to choose the preferred signature component. However, the signature operations will always be performed by the active signature component, which is not necessarily the selected one.

The options page should also allow to invoke a separate options page for the particular extensions.

Options signature components.png

Note: signature components may need to be configured. The options button in the image above could open a new modal Window. But then there would be a stack of three windows. The option window could also replace the current options page. Then it would have to offer some kind of Back button to restore the previous view. This would be the best integration but difficult and time consuming to implement. Another possibility is to introduce a new node "Signature Components". Its first child element (leaf) would then contain all the available components and all other leaves under that node could be the options pages of the respective signature components.

No active signature component

This occurs in these situations:

  • no document is opened (backing window)
  • there is no signature component installed, which can deal with the signatures in the current document

The first case is not important, because there is neither a signature to be validated nor a document to be signed. However, the second case needs to be dealt with because this causes users two inconveniences. Firstly, they cannot validate the signature and secondly, the document is read-only (see 'The active signature component).

Users can run into this situation, when they load a document. Then a message box will be displayed, which at best contains these information:

  • Information about the used standards, profiles, specifications, etc. which the signature complies with
  • Information about the signature component which created the extension. It could contain a link to the web page (e.g. Extensions Repository) where this component can be downloaded.
  • A note that the document can only be modified if a suitable signature component is installed (see 'The active signature component').

Msb unknown sig.png

These information are only available if the signature meta data are accessible. That is, the document must be loaded and the meta data must exist. While the latter can be made mandatory, the first condition may not always be met. This can be the case if the document file has a signature file attached, or the document is contained in a CMS "envelope", etc. Loading this document requires a particular filter which would be provided by the respective signature component. And if it is not installed, the document will not be loaded at all.

Therefore OOo needs a mechanism to recognize that a file is a signed document. This can be easily done by providing a new file extension, for example .odts (the -s- stands for signed). OOo may not be able to load an .odts file, but it knows that it is signed document can inform the user accordingly.

One could also invent specific file extensions for signature formats. Then OOo could display more accurate information about the needed signature component. This, however, requires that there need some built-in information to OOo and the information must be provided by the publishers of the signature extensions.


no new file extension
No message box. OOo would treat the document as every other unknown file format.
one new file extension
The message indicates that the document is signed. The message box can offer to forward to the extensions repository to look for signature components. The link could contain a search request for "signature component". Users must, however, know what kind of signature is used. They can obtain this information from the author, the web page where they got the document from, etc.
Msb unknown sig3.png

several file extensions
A message indicates the specification which the signature complies to. The message box can offer to forward to extensions repository to look for signature components which implement this specification. The link would therefore contain an respective search request.
Msb unknown sig2.png

Removing signatures

Signatures are removed in two situations:

  • the user actively removes a signature
  • the signed part of the document was modified

The latter mentions explicitly the "signed part". This is because signatures may be created for parts of the document, such as paragraphs, regions, particular streams within the zip package, etc. Modifications outside of the signed areas do not render the signature invalid. In these cases, signatures need not be removed. For example, the current implementation allows to sign the macros separately. Modifying the text in the writer document does not invalidate the macro signature.

Different signature components can write there signatures in different ways. Even if the two components adhere to the same standard, they still may write the signature differently. For example, certificate revocation lists could be contained in a signature (signature refers here to the whole "package" containing the actual signatures, countersignatures, certificates, certificate revocation lists, time stamps) or they could be referenced. In the first case the signature would be in one file and in the second case it would be in two or more files.

Similarly, the current signature implementation creates two separate signatures, one for the whole document and the other for macros. Another signature component, which also complies with the W3C XML Digital Signature standard, but only signs the whole document, would not be aware of the macro signature.

On must also be aware, that removing a signature not just means to delete a file. In many cases the signature data structure must be modified. For example, there could be a separate signature file, which contains a couple of "real" signatures (pure RSA, DSA, etc.) from different persons. Deleting the signature of one person requires to modify the data structure itself.

These examples show, that deleting requires specific knowledge of the signature. Therefore the deletion of a signature or part of it must be performed by a suitable signature component, which is the active signature component. If there is no active signature component then a signature cannot be removed.

If only the signature component can remove signatures, then it must be notified whenever the user has started an action which will modify the document file. In most cases this will be a 'save' operation. But there may be other places, for example, saving or deleting a version of the document will also modify the file.

Menus and menu items

OOo 3.0 has two distinct menu entries for signatures, one for macro and one for document signatures. Other signature components may only support one signature for the whole document. Then the macro signature menu item would no longer be necessary. Or a signature component allows to sign particular "aspects" of the document, similar to OOo's document and macro signature. This could necessitate additional menu items. A signature component may also require separate menu items for the sign and validation operations. In contrast, the current menu items fulfill both purposes. For the best integration of signature components it is therefore desirable, that every component defines their own menu entries. Another problem is that menu items need to be changed dynamically as the following scenarios show:

  • Backing window
No menus or menu items of any signature component are displayed.
  • Unsigned document
When the user creates a new document then the menus and menu items of the signature component, which is set in the users preferences (options dialog), will be displayed.
  • Signed document with matching signature component
This scenario occurs when either a new document was just signed or a signed document was loaded and OOo has a suitable signature component installed. The menus and menu items of the 'suitable signature component' are displayed.
  • Signed document without matching signature component
This will occurs when the user loads a signed document and doesn't have a suitable signature component installed. In this case no menus and menu items of a signature component are displayed.
  • Unsigned document and changed preference for signature component
That is, while an unsigned document is displayed the user selects a different signature component in the options dialog. As a consequence the menus and menu items of the previously selected signature component disappear and those of the now selected signature component are displayed.

Menus, menu items, icons and commands are defined in the SignatureComoponent.xcu. The Signature Component Service Provider takes care of creating and removing those items when the respective signature component was chosen by the SCSP as the active signature component.

Status bar

The current implementation shows the result of the signature validation in the status bar. There are four states:

  • not signed (no icon)
  • valid signature
  • invalid signature
  • valid signature but certificate could not be validated

For every state, except when there is no signature, exists a tool tip string. Double clicking on this status bar field will start validation (again) and show the results in a window. The currently used states are not sufficient. For example, XAdES defines these states:

  • valid
  • invalid
  • incomplete validation

One could also show an only icon/text: “contains signature”. Clicking on the status bar area will then trigger the validation (as well as in all other cases) and only then the status will be visible.

Because of the varying requirements of different signature components, it is reasonable to have them define their own states. Therefore the signature components can define their states, along with icons and strings, in the SignatureComponent.xcu. If they do not define states, then the existing states are used.

Preparations for signing

To make sure that all modifications of a document are also included when the document is signed, it must be enforced that the document is saved before the signing operation starts. A message box is displayed, which asks the user to save.

Do you wanne save msb.PNG

When the user agrees to save, then there are two different ways.

  • The document was created in this session (new document). Then a file dialog needs to be displayed, because the user must determine its name and where the file is to be saved.
  • The document was loaded. Then the document can be saved directly without user interaction.

Because the signature component receives the notification of the sign command, this handling could be implemented by the signature component itself. On the other hand, the SCSP could provide this dialog and the save procedure.

[Todo: Decide where the code is implemented and define the interface for the SCSP if necessary]

In case a document is signed and modified, the user will be displayed a particular message box in OOo 3.0:

Save and loose sigs msb.PNG

Regarding the signature framework there are two things to be considered. First, saving the document need not necessarily invalidate all signatures. For example, there could be signed parts of the document, which were not modified. Therefore the dialog should display exactly which signatures will be removed. Second, both, finding out which signatures have become invalid and removing these, can only be done by the active signature component.

Similar to the previous message box the actual save operation could be performed by the SCSP.

OOo 3.0 can only sign Open Document files. If one tries to load a file using a different format, then this will be refused and a message box is displayed:

Save opendoc before sig msb.PNG

The SCSP can provide a mechanism to check if the loaded document is in Open Document format and show the message box. However, it must be triggered by the signature component, because only the signature component receives the notification when the user starts the signing operation, for example by clicking the respective menu item.

Signing / Validation

It is still unclear if the signature component shall be called by the SCSP and be provided all necessary information so as to perform the signature operation or if it obtains all information on its own by using the API. The protocol handler of the signature component receives a frame object, which eventually provides the URL and storage (XStorage) of the document.

The latter approach is more flexible. Fore example, the service could decide to instantiate a particular "XStorage" service that allows to write the signature in a special way into the zip file. There could be several specialized implementation of such services and therefore one cannot provide an interface which meets all needs.

Copying signatures

There are some occasions when OOo creates a copy of a document and the signatures shall be retained. For example:

  • A template containing macro signatures is saved as document
  • OOo loads a corrupted document and repairs it
  • OOo reads a locked or read-only document and creates a copy so that the user can modify it.

Signature components may need to provide a list of the signature files, so that OOo can copy them. OOo may not know all possible names of signature stream, which can be contained in a document. The names can be contained in the SignatureComponent.xcu.

One must also take into account that there could be detached signatures in a separate file. These files need to be copied as well.

Consistency check of the document

OOo performs a consistency check of the document (as of OOo 3.2) when loading it. It must take unknown signature streams into account. To do this, every signature component must provide a list of the signature streams it creates. The list would be in the SignatureComponent.xcu.

Handling of other file formats

Saving a document using a non - Open Document format, will most likely invalidate the signatures. But this may not always be the case, for example, when the target format is a similar XML format. The signature component also needs to supply an appropriate filter, so as to write that format.

The SCSP needs to receive a save notification, ask the active signature component or consult the SignatureComponent.xcu if it can write this format including the signatures. If it cannot, then this message box is displayed:

Save other format remove all sig msb.PNG

Note: This scenario may be too exotic. Maybe the SCSP should always show this message box.

How to migrate ODF 1.1/1.2 signature handling

The signature created by OOo for ODF 1.2 has slightly changed. ODF 1.1 signatures can still be validated, but one cannot modify signatures in an ODF 1.1 file. It is only possibly to write signatures in ODF 1.2 files. This behavior need to be considered when adapting the signature service, which is currently used in OOo, to a signature component.

It may be useful to allow signature components to only validate particular formats. For example, the default OOo signature component could create/validate ODF 1.2 conform signatures but only validate ODF 1.1 conform signatures.

Other issues

It is currently not possible to access the contents of the META-INF folder through an 'XStorage' implementation.

Signature components may need exclusive access to the document file, even when writing a detached signature. But often the file is locked.

Personal tools