How to use digital Signatures

From Apache OpenOffice Wiki
Jump to: navigation, search

1. Where to get a Certificate

First of all you need a valid digital certificate. You can get one for free by various Security Providers, for Germany especially for people from Hamburg, you can get such a certificate from the Trustcenter ([1]), other people may have a look at Comodo([2]), StartSSL ([3]) or CAcert ([4]). These companies offer such a certificate for free with an expiration time of one year. After that you have to renew it if you like. If not you will not be able to sign documents any longer.

If you do not trust these companies or want a higher Class Certificate you need to pay some money and the company will validate your personal data to make sure that you are the one you say you are. Such companies are Globalsign ([5]), Verisign ([6]) and also Trustcenter and StartSSL. In combination with a Freemail Account you can get a digital certificate for Germany at Web.de ([7]).

1.1 How to make a certificate useable for OpenOffice/StarOffice

OpenOffice supports both the internal certificate store for some systems and the Network Security Service of Mozilla. If you follow the process to get a certificate this will be installed into the keystore of your system. (Please find additional details on this part on the Certificate Detection page.) Once installed, you should be able to view your certificate through a variety of means depending on your system.

1.1.1 Prerequisites on Windows This certificate information needed by StarOffice / OpenOffice.org relies on the Crypto engine on the users system. On Windows the Microsoft Crypto API is used, therefore nothing has to be done if the Internet Explorer was used to get the Certificate. In case you've used Mozilla or Firefox, you have to export your certificate into a file from the Mozilla Certificate store and import it into the Microsoft keystore. To do so, just go to your settings dialog in Mozilla and choose :


-Manage Certificates from it.
-Select the Certificate to export and click on the button Backup
-Find a place were you can save the file and name it
-Follow the instructions given by Mozilla 
-To import the Certificate into the Microsoft Cryptoengine, do the following:
 -travel to the location of the now exported file by using your preferred file manager and 
 -double click the file. 
 -Follow the instructions and that's it. 
 -You have transferred your certificate into the Microsoft keystore of your Windows installation.


1.1.2 Prerequisites on Linux / Solaris

To use your Certificate for digital signing of documents on Linux or Solaris we need some prerequisites :

- A certificate (obtained from a Certificate Authority)
- Mozilla Network Security Services. 

If you install either Mozilla Firefox or Thunderbird, the Mozilla NSS services will likely be installed as part of these packages.


StarOffice / OpenOffice.org is looking for a certificate in the mentioned profiles according to the following search order :

a.) The environment variable MOZILLA_CERTIFICATE_FOLDER
b.) The Thunderbird profile
c.) The Mozilla suite profile
d.) The Firefox profile.

This is especially useful to know as Debian and maybe Fedora Linux Installations seem to set the profile names in another way as suggested by the Mozilla developers. In this case the Certificates are not shown in the digital signature dialog of the Office suite. In this case, locate the appropriate profile folder and set the Environment Variable MOZILLA_CERTIFICATE_FOLDER accordingly. See Certificate Detection for how to set MOZILLA_CERTIFICATE_FOLDER correctly.

It is also necessary that the trust settings for the root certificates are set to trust the certificate to identify web sites and e-mail users.


1.2 Using card readers

There are loads of different types of readers and smart cards. Please read first the documentation of your reader and card and install all necessary software which comes with it.

If you use Linux, then follow the documentation about how to add smart card support to Firefox/Thunderbird. In general, this will require to add a particular library (a pkcs11 module) in the device manager (security devices) in Firefox/Thunderbird. The device manager can be found in the options dialog under the Advanced tab page.

With some readers/cards it is sufficient to install opensc and pcscd. pcscd is a deamon, which is located in /etc/init.d. Then one has to add opensc-pkcs11.so, which may be found under /usr/lib, in the device manager.


2. How to sign a document

Edit the document you want to sign and save it. Now select Digital Signatures from the File Menu. If you get a warning about a missing Mozilla profile, have a look at chapter 1.1.1 please. You probably use a Debian or Fedora Linux and haven't set the environment variable in the correct way.

If all is properly set, you get the digital signatures dialog and can click on the Add button. On Linux and Solaris you're asked for the password for accessing the used keystore, on Windows it depends on the settings made on importing the certificate. Now your stored certificates are shown. Please select the one you want to use and than click on Ok. After that you will be back in StarOffice / OpenOffice.org Digital Signatures dialog. This dialog will show a small icon in front of the textual representation of the certificate used to sign the Document.


2.1 How to sign a Macro

To sign a Macro you have two possible ways.

1.)Use Tools – Macro – Digital Signature
2.)Use File – Digital Signature within the BASIC Editor of StarOffice / OpenOffice.org

The procedure of adding a certificate to the Macro is the same as used for documents.

3. Error messages and visual aids

3.1 Error messages on loading of documents

You only get a message on loading the document if the signature of the document and / or the signature of the containing macros is broken. In this case the execution of macros is stopped and you can only activate macros by setting the security level to low and re-loading the document. But this is not recommended. Or remove the broken signature from the document and reload it. In this case make sure the macros contained in the document are not malicious.

3.2 Visual Aids

We have four visual aids for the possible states of a document signature.

A sheet with a stylised red seal stating that the document signature(s) are OK and no alteration of the document occurred since the last signing.

The addition (signed) to the title bar of an opened signed document.

A sheet with a stylised red seal and a small yellow triangle with exclamation mark stating that the document signature(s) are OK and no alteration of the document occurred since the last signing but at least one of the used certificates could not be validated. This can be caused by a not available root certificate from the Issuer of one of the certificates used or a not possible connection to the server containing the Revocation List for the Certificate Issuer. This is just an informal message, the document itself isn't changed after signing. But the decision on how far you can trust this document is up to you. The used certificate is maybe outdated or revoked.

A yellow triangle with black exclamation mark showing that the document signature is broken. So this document has been altered in some way and therefore you should not trust it's content.

These visual aids will be displayed in the digital signature dialog and the status bar. For the '(signed)' text, this one is shown in the title bar of the document window next to the file name.

4. Trusted Macro Source

To add a certificate as a trusted macro source, open a document signed with the certificate you want to trust. Then use the dialog that pops up to always trust macros from that source.

See also

Personal tools