Thomas
Baumgart

    ipwizard@users.sourceforge.net

2005-06-01
0.7

# File Formats

This chapter describes the formats in which &kappname; stores it's data in permanent form on the users disk. In general, &kappname; stores it's information in form of an XML document. Depending on the actual format, this XML document will be written

- as plain text file encoded in UTF-8,

- as compressed file using GZIP compression,

- as encrypted file using GPG encryption or

- as anonymous plain text file encoded in UTF-8 but with all your personal data scrambled.

## Plain text file

This is the most space consuming format supported as no compression is performed. It is usually not used by normal user and provided to support debugging purposes and the capability to modify the file manually. If you end a filename in `.xml` the file will be stored in this format.

Manual modification of the file is not recommended to the normal user and should only be performed if the internal working of &kappname; is fully understood or instructions from the developers tell you what to do. Don't blame the &kappname; developers if you screw up your data: You have been warned!

## GZIP-compressed file

This is the normal format used by &kappname; when you store a file with the extension `.kmy`

If encryption has been selected, the file will be stored encrypted.

If you want to look at a GZIP compressed file, rename it to a filename ending in `.gz` (e.g. `myfinances.kmy` into `myfinances.kmy.gz`, then use `gunzip` to uncompress the file and look at it. You don't have to compress it before loading it into &kappname; the next time, because &kappname; can read the uncompressed data as well. Nevertheless, if you save it thereafter, it will be saved compressed again. Use the .xml extension to write it in uncompressed format.

## GPG-encrypted file

Using the GPG-encrpyted file format is a very secure method to store your personal finance data on your disk. When &kappname; has been instructed through the settings dialog to store your data encrypted, it will cipher the data using GPG and the key you provided before actually storing it on disk. When opening an encrypted file, you have to provide the passphrase necessary to open your keyring. The encrypted file itself will be stored in GPG's ASCII armored format.

When using GPG encryption, GPG also compresses the file, so no extra compression is necessary.

### GPG-Keys

If you have not done so already for mail encryption, you need to generate a key-pair in order to be able to use the GPG encryption feature of &kappname;. Also, GPG must be installed on your system.

The details about howto generate a key-pair, howto take care of it are beyond the scope of this document. A Mini Howto on this subject can be found at http://webberr.dewinter.com/gnupg_howto/english/GPGMiniHowto.html.

### Setting the keys in &kappname;

On the security page of the settings dialog you have a field where you can enter the key-id of the key that should be used for encryption and decryption. You can use either the key-id, the e-mail address associated with this key or any other valid GPG key identification as value for this field. When you enter the key-id, &kappname; will check it's validity and turn on a green LED in the dialog if a key is found.

Make sure, you have both, the public and the private key for this id. If you don't own the private key for the id entered, you will not be able to open the file again.

### The &kappname; recover key

Also on this page of the settings dialog you have the choice to select supplemental encryption with the &kappname; recover key. This option is available to you, if that key is stored in your GPG keyring. Selecting this option will allow you to recover your data even in the case you loose your own private key. This is possible, because the data is not only encrypted for your own key, but also for the &kappname; recover key. This key is only available to selected &kappname; developers (at the time of writing only to the author).

Under normal circumstances, you will open/save/close your file as usual. In the abnormal case of loss of your key, you have the chance to contact one of the developers who has access to the &kappname; recover key and request help to recover your data. You may contact the developers via e-mail to the &kappname; developer mailing list at &devlist;.

## Anonymous file

This format is not intended to be used for normal data storage. It is supported as a method to supply the &kappname; development team with your file in case of a problem without disclosing any of your financial data. If instructed by the developers use the Save as... menu item to store your data in anonymous format by selecting `.anon.xml` as file extension. To verify that your problem still exists, reload this anonymized file and try to duplicate your problem. If it shows, send the file to the developer mailing list at &devlist; for further investigation. If the problem does not show ... well, I don't want to think about this scenario right now.