<?xml version="1.0" encoding="UTF-8"?>
<chapter id="details.formats">
<chapterinfo>
  <authorgroup>
    <author
>&Thomas.Baumgart; &Thomas.Baumgart.mail; </author>
  </authorgroup>
  <date
>2010-07-25</date>
  <releaseinfo
>4.5</releaseinfo>
</chapterinfo>

<title
>Bestandsformaten</title>

<para
>Unless you choose to use a <link linkend="details.database"
>relational database</link
>, &kappname; will store all your financial information in a file ending in .kmy. Also, unless you use a <link linkend="firsttime.launch"
>command line option</link
> that tells it not to do so, when you launch &kappname;, it will open the last file it had open. However, it is important to know that there is more than one type of file &kappname; can use to hold your financial data. </para>

<para
>This chapter describes the formats in which &kappname; stores its data in permanent form on the user's storage device. In general, &kappname; stores its information in form of an &XML; document. Depending on the actual format, this &XML; document will be written <itemizedlist>
  <listitem
><para
>als een <link linkend="details.formats.plain"
>platte tekst bestand</link
> gecodeerd in UTF-8,</para
></listitem>

  <listitem
><para
>als een <link linkend="details.formats.compressed"
>gecomprimeerd bestand</link
> met GZIP-compressie,</para
></listitem>

  <listitem
><para
>als een <link linkend="details.formats.encrypted"
>versleuteld bestand</link
> met GPG-versleuteling of</para
></listitem>

  <listitem
><para
>als een <link linkend="details.formats.anonymous"
>anoniem platte tekst bestand</link
> gecodeerd in UTF-8 maar met alle uw persoonlijke gegevens door elkaar gehusseld.</para
></listitem>
</itemizedlist>
</para>

<sect1 id="details.formats.plain">
<title
>Platte-tekstbestand</title>
<para
>This is the most space consuming format supported, as no compression is performed. It is not intended for normal use, and is provided to support debugging purposes and the capability to modify the file manually. If you end a filename in <literal role="extension"
>.xml</literal
>, the file will be stored in this format. <caution
> <para
>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 if 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! </para>
</caution>
</para>
</sect1>

<sect1 id="details.formats.compressed">
<title
>GZIP-gecomprimeerd bestand</title>
<para
>Dit is het normale formaat dat door &kappname; wordt gebruikt wanneer u een bestand opslaat met de extensie <literal role="extension"
>.kmy</literal
>. </para>

<note>
  <para
>Als <link linkend="details.formats.encrypted"
>versleuteling</link
> is geselecteerd, zal het bestand versleuteld worden opgeslagen. </para>
</note>

<para
>If you want to look at the contents of a GZIP compressed file, rename it to a filename ending in <literal role="extension"
>.gz</literal
> (&eg;, rename <filename
>myfinances.kmy</filename
> to <filename
>myfinances.kmy.gz</filename
>), then use <command
>gunzip</command
> 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 <link linkend="details.formats.plain"
>.xml</link
> extension to write it in uncompressed format. </para>
</sect1>

<sect1 id="details.formats.encrypted">
<title
>GPG-versleuteld bestand</title>
<para
>Using the GPG-encrypted file format is a very secure method of storing your personal finance data on your storage device. 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. 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 <emphasis
>ASCII armored</emphasis
> format. <note
> <para
>When using GPG encryption, GPG also compresses the file, so no extra compression is necessary. </para>
  </note>
</para>

<sect2 id="details.formats.encrypted.gpgkeys">
<title
>GPG-Keys</title>
<para
>If you have not done so already for mail encryption, you need to generate a key-pair in order to use the GPG encryption feature of &kappname;. Also, <application
>GPG</application
> must be installed on your system. </para>

<para
>The details about how to generate a key-pair and how to take care of it are beyond the scope of this document. A Mini Howto on this subject can be found at <ulink url="http://www.gnupg.org/documentation/howtos.en.html"
>http://www.gnupg.org/documentation/howtos.en.html</ulink
>. </para>
</sect2>

<sect2 id="details.formats.encrypted.keysettings">
<title
>Setting the keys in &kappname;</title>
<para
>On the encryption page of the settings dialog, there is a drop down list where you can select the key that should be used for encryption and decryption. Additionally you can find a field where you can enter the key-id of a key not in the listbox. You can use either the key-id, the email address associated with this key, or any other valid GPG key identification as the value for this field. When you enter the key-id, &kappname; will check its validity and display a green LED icon in the dialog if a key is found. <caution
> <para
>Make sure you have both the public and the private key for this id. If you do not own the private key for the id entered, you will not be able to open the file again. </para>
  </caution>
</para>
</sect2>

<sect2 id="details.formats.encrypted.recoverkey">
<title
>The &kappname; recover key</title>
<para
>Also on this page of the settings dialog you have the choice of selecting supplemental encryption with the &kappname; recover key. This option is available to you if that key is stored in your <application
>GPG</application
> keyring. Selecting this option will allow you to recover your data even in the case you lose 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). As of the release of &kappname; version 4.5, the release key is set to expire on 3 January 2015. </para>

<para
>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 email to the &kappname; developer mailing list at &devlist;. </para>
</sect2>
</sect1>

<sect1 id="details.formats.anonymous">
<title
>Anonymous file</title>
<para
>This format is not intended to be used for normal data storage. It is supported so that in case of a problem, you can supply the &kappname; development team with your file without disclosing any of the confidential details in your financial data. For example, it changes institution, account, payee, and category names to strings such as "I000001" and "A000001," it makes similar changes to all data such as account numbers, and it also randomly changes the amounts of transactions. </para>

<para
>If instructed by the developers, use the <guimenuitem
>Save as...</guimenuitem
> menu item to store your data in anonymous format by selecting <literal role="filter"
>Anonymous files</literal
> as the filter. This also changes the file extension to <literal role="extension"
>.anon.xml</literal
>. </para>

<para
>To verify that your problem still exists, reload this anonymized file and try to duplicate your problem. If the problem is still present, 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. </para>
</sect1>
</chapter>

