Revision as of 11:43, 5 February 2009

Objectives

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 OpenOffice.org (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 OpenOffice.org extensions and can therefore be updated independent of OOo.

Definitions

Signature Component

Consists of code and data needed to create and verify a digital signature applied to an ODF document. It is delivered as OpenOffice.org extension.

Signature Component Service Provider (SCSP)

The SCSP is a service which manages the installed signature components and makes it easier to develop them.

SignatureComponent.xcu

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.

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 information are contained in a new stream in the ODF document. It provides additional information about the signature. It is used to:

• prevent using different types of signatures (see 'Using different types of signatures' )
• uniquely identifying the signature component (validation, removal, resigning, countersigning)
• inform the user that they need a signature component to verify the signatures
• identify the signature files which can be copied from a template to a document

A signature component which creates a detached signature (e.g. a separate file is created) must also write the meta information into the document.

Whenever a document is loaded, then it is investigated for signatures. Because of the meta data it is not necessary to invoke the signature components just to find out about them. Doing so may cause the loading of the Java or other runtimes, which can be costly. That is, the performance impact for unsigned documents at load time will be little.

Selection of the signature component for writing the signature

When different signature extensions are installed, then users can select in an options page which one they want to use for signing. This selection, however, does not determine the signature component used for validating a signature.

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

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.

Selection of the signature component for validating the signature

To verify a signature it is necessary to determine the proper signature component which is to carry out this operation. The framework will utilize the Signature meta data to choose the correct component. If the document contains a signature for which no suitable signature component is installed, then a message is displayed that tells users that they need to install a particular component before the signature can be validated. The message box should contain:

• 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. OpenOffice.org 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 'Removing signatures'.

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. For further information and possible solutions refer to New file type for signed documents.

Dependent on if we introduce no, one or several new file types, the user can be displayed:

• No particular message, if we do not introduce a new file extensions. The office would treat the document as every other unknown file format.
• A message, indicating that the document is signed. The message box can offer to forward to the OpenOffice.org 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.

• A message, indicating the specification which the signature complies to. The message box can offer to forward to OpenOffice.org extensions repository to look for signature components which implement this specification. The link would therefore contain an respective search request.

The signature component selected for validating the signature need not be the same which was selected by the user in the options dialog (see ' The active signature component').

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. See 'Identifying a suitable signature component' for details about how the signature component is determined.

If there is no suitable signature component installed, then signatures cannot be removed. The consequence is, that the document must not be modified which also prohibits the creation of additional signatures. That is, the document with an unknown signature type (that is, no suitable signature component is installed) will be loaded as read-only. How this is communicated to the user is explained in paragraph Selection of the signature component for validating the signature.

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. There can be only one active signature component at a time.

• 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 ' Identifying a suitable signature component'

When the user selects a different signature component in the options dialog, 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 ' Identifying a suitable 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. In this case it is not allowed to add or modify or remove the signature (see ' Removing signatures').
• 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.

See also ' Identifying a suitable signature component '.

Identifying a suitable signature component

Todo

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.

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