Warning, /office/kmymoney/doc/details-formats.docbook is written in an unsupported language. File is not indexed.

 <?xml version="1.0" encoding="UTF-8"?>
 <chapter id="details.formats">
 <chapterinfo>
   <authorgroup>
     <author> &Thomas.Baumgart; &Thomas.Baumgart.mail; </author>
   </authorgroup>
   <date>2014-08-30</date>
   <releaseinfo>4.7.01</releaseinfo>
 </chapterinfo>
 
 <title>File Formats</title>
 
 <para>
   Unless you choose to use a <link linkend="details.database">relational
   database</link>, &kmymoney; will store all your financial information in a
   file ending in <filename class="extension">.kmy</filename>. Also, unless you use a <link
   linkend="firsttime.launch">command line option</link> that tells it not to do
   so, when you launch &kmymoney;, it will open the last file it had open.
   However, it is important to know that there is more than one type of file
   &kmymoney; can use to hold your financial data.
 </para>
 
 <para>
   This chapter describes the formats in which &kmymoney; stores its data in
   permanent form on the user's storage device. In general, &kmymoney; stores its
   information in form of an &XML; document. Depending on the actual format, this
   &XML; document will be written:
 
 <itemizedlist>
   <listitem><para>as a <link linkend="details.formats.plain">plain text
     file</link> encoded in UTF-8,</para></listitem>
 
   <listitem><para>as a <link linkend="details.formats.compressed">compressed
     file</link> using GZIP compression,</para></listitem>
 
   <listitem><para>as an <link linkend="details.formats.encrypted">encrypted
   file</link> using GPG encryption, or</para></listitem>
 
   <listitem><para>as an <link linkend="details.formats.anonymous">anonymous
     plain text file</link> encoded in UTF-8 but with all your personal data
     scrambled.</para></listitem>
 </itemizedlist>
 </para>
 
 <sect1 id="details.formats.plain">
 <title>Plain text file</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 <filename class="extension">.xml</filename>, 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 &kmymoney; is fully
     understood or if instructions from the developers tell you what to do. Don't
     blame the &kmymoney; developers if you screw up your data: You have been
     warned!
   </para>
 </caution>
 </para>
 </sect1>
 
 <sect1 id="details.formats.compressed">
 <title>GZIP-compressed file</title>
 <para>
   This is the normal format used by &kmymoney; when you store a file with the
   extension <filename class="extension">.kmy</filename>.
 </para>
 
 <note>
   <para>
     If <link linkend="details.formats.encrypted">encryption</link> has been
     selected, the file will be stored encrypted.
   </para>
 </note>
 
 <para>
   If you want to look at the contents of a GZIP compressed file, rename it to a
   filename ending in <filename class="extension">.gz</filename> (&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 &kmymoney; the next time, because &kmymoney; 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"><filename
   class="extension">.xml</filename></link> extension to write it in uncompressed
   format.
 </para>
 </sect1>
 
 <sect1 id="details.formats.encrypted">
 <title>GPG-encrypted file</title>
 <para>
   Using the GPG-encrypted file format is a very secure method of storing your
   personal finance data on your storage device. When &kmymoney; 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
   &kmymoney;. 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="https://www.gnupg.org/documentation/howtos.en.html">https://www.gnupg.org/documentation/howtos.en.html</ulink>.
 </para>
 </sect2>
 
 <sect2 id="details.formats.encrypted.keysettings">
 <title>Setting the keys in &kmymoney;</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, 
   &kmymoney; 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 &kmymoney; recover key</title>
 <para>
   Also on this page of the settings dialog you have the choice of selecting
   supplemental encryption with the &kmymoney; 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 &kmymoney; recover key. This
   key is only available to selected &kmymoney; developers (at the time of
   writing only to the author).  As of the release of &kmymoney; version 4.7, the
   recover 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 &kmymoney; recover key and request help
   to recover your data. You may contact the developers via email to the
   &kmymoney; 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 &kmymoney;
   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 <filename class="extension">.anon.xml</filename>.
 </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>