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

0001 <?xml version="1.0" encoding="UTF-8"?>
0002 <chapter id="details.formats">
0003 <chapterinfo>
0004   <authorgroup>
0005     <author> &Thomas.Baumgart; &Thomas.Baumgart.mail; </author>
0006   </authorgroup>
0007   <date>2014-08-30</date>
0008   <releaseinfo>4.7.01</releaseinfo>
0009 </chapterinfo>
0011 <title>File Formats</title>
0013 <para>
0014   Unless you choose to use a <link linkend="details.database">relational
0015   database</link>, &kmymoney; will store all your financial information in a
0016   file ending in <filename class="extension">.kmy</filename>. Also, unless you use a <link
0017   linkend="firsttime.launch">command line option</link> that tells it not to do
0018   so, when you launch &kmymoney;, it will open the last file it had open.
0019   However, it is important to know that there is more than one type of file
0020   &kmymoney; can use to hold your financial data.
0021 </para>
0023 <para>
0024   This chapter describes the formats in which &kmymoney; stores its data in
0025   permanent form on the user's storage device. In general, &kmymoney; stores its
0026   information in form of an &XML; document. Depending on the actual format, this
0027   &XML; document will be written:
0029 <itemizedlist>
0030   <listitem><para>as a <link linkend="details.formats.plain">plain text
0031     file</link> encoded in UTF-8,</para></listitem>
0033   <listitem><para>as a <link linkend="details.formats.compressed">compressed
0034     file</link> using GZIP compression,</para></listitem>
0036   <listitem><para>as an <link linkend="details.formats.encrypted">encrypted
0037   file</link> using GPG encryption, or</para></listitem>
0039   <listitem><para>as an <link linkend="details.formats.anonymous">anonymous
0040     plain text file</link> encoded in UTF-8 but with all your personal data
0041     scrambled.</para></listitem>
0042 </itemizedlist>
0043 </para>
0045 <sect1 id="details.formats.plain">
0046 <title>Plain text file</title>
0047 <para>
0048   This is the most space consuming format supported, as no compression is
0049   performed. It is not intended for normal use, and is provided to support
0050   debugging purposes and the capability to modify the file manually. If you end
0051   a filename in <filename class="extension">.xml</filename>, the file will be
0052   stored in this format.
0054 <caution>
0055   <para>
0056     Manual modification of the file is not recommended to the normal user, and
0057     should only be performed if the internal working of &kmymoney; is fully
0058     understood or if instructions from the developers tell you what to do. Don't
0059     blame the &kmymoney; developers if you screw up your data: You have been
0060     warned!
0061   </para>
0062 </caution>
0063 </para>
0064 </sect1>
0066 <sect1 id="details.formats.compressed">
0067 <title>GZIP-compressed file</title>
0068 <para>
0069   This is the normal format used by &kmymoney; when you store a file with the
0070   extension <filename class="extension">.kmy</filename>.
0071 </para>
0073 <note>
0074   <para>
0075     If <link linkend="details.formats.encrypted">encryption</link> has been
0076     selected, the file will be stored encrypted.
0077   </para>
0078 </note>
0080 <para>
0081   If you want to look at the contents of a GZIP compressed file, rename it to a
0082   filename ending in <filename class="extension">.gz</filename> (&eg;,
0083   rename <filename>myfinances.kmy</filename>
0084   to <filename>myfinances.kmy.gz</filename>), then use <command>gunzip</command>
0085   to uncompress the file and look at it. You don't have to compress it before
0086   loading it into &kmymoney; the next time, because &kmymoney; can read the
0087   uncompressed data as well. Nevertheless, if you save it thereafter, it will be
0088   saved compressed again. Use the <link linkend="details.formats.plain"><filename
0089   class="extension">.xml</filename></link> extension to write it in uncompressed
0090   format.
0091 </para>
0092 </sect1>
0094 <sect1 id="details.formats.encrypted">
0095 <title>GPG-encrypted file</title>
0096 <para>
0097   Using the GPG-encrypted file format is a very secure method of storing your
0098   personal finance data on your storage device. When &kmymoney; has been
0099   instructed through the settings dialog to store your data encrypted, it will
0100   cipher the data using GPG and the key you provided before actually storing
0101   it. When opening an encrypted file, you have to provide the passphrase
0102   necessary to open your keyring. The encrypted file itself will be stored in
0103   GPG's <emphasis>&ASCII; armored</emphasis> format.
0104   <note>
0105     <para>
0106       When using GPG encryption, GPG also compresses the file, so no extra
0107       compression is necessary.
0108     </para>
0109   </note>
0110 </para>
0112 <sect2 id="details.formats.encrypted.gpgkeys">
0113 <title>GPG-Keys</title>
0114 <para>
0115   If you have not done so already for mail encryption, you need to generate a
0116   key-pair in order to use the GPG encryption feature of
0117   &kmymoney;. Also, <application>GPG</application> must be installed on your
0118   system.
0119 </para>
0121 <para>
0122   The details about how to generate a key-pair and how to take care of it are
0123   beyond the scope of this document.  A Mini Howto on this subject can be found
0124   at <ulink url="https://www.gnupg.org/documentation/howtos.en.html">https://www.gnupg.org/documentation/howtos.en.html</ulink>.
0125 </para>
0126 </sect2>
0128 <sect2 id="details.formats.encrypted.keysettings">
0129 <title>Setting the keys in &kmymoney;</title>
0130 <para>
0131   On the encryption page of the settings dialog, there is a drop down 
0132   list where you can select the key that should be used for encryption and 
0133   decryption. Additionally you can find a field where you can enter the 
0134   key-id of a key not in the listbox. You can use either the key-id, the 
0135   email address associated with this key, or any other valid GPG key 
0136   identification as the value for this field. When you enter the key-id, 
0137   &kmymoney; will check its validity and display a green LED icon in the 
0138   dialog if a key is found.
0139   <caution>
0140     <para>
0141       Make sure you have both the public and the private key for this id. If you
0142       do not own the private key for the id entered, you will not be able to
0143       open the file again.
0144     </para>
0145   </caution>
0146 </para>
0147 </sect2>
0149 <sect2 id="details.formats.encrypted.recoverkey">
0150 <title>The &kmymoney; recover key</title>
0151 <para>
0152   Also on this page of the settings dialog you have the choice of selecting
0153   supplemental encryption with the &kmymoney; recover key. This option is
0154   available to you if that key is stored in your <application>GPG</application>
0155   keyring. Selecting this option will allow you to recover your data even in the
0156   case you lose your own private key. This is possible because the data is not
0157   only encrypted for your own key, but also for the &kmymoney; recover key. This
0158   key is only available to selected &kmymoney; developers (at the time of
0159   writing only to the author).  As of the release of &kmymoney; version 4.7, the
0160   recover key is set to expire on 3 January 2015.
0161 </para>
0163 <para>
0164   Under normal circumstances, you will open/save/close your file as usual. In
0165   the abnormal case of loss of your key, you have the chance to contact one of
0166   the developers who has access to the &kmymoney; recover key and request help
0167   to recover your data. You may contact the developers via email to the
0168   &kmymoney; developer mailing list at &devlist;.
0169 </para>
0170 </sect2>
0171 </sect1>
0173 <sect1 id="details.formats.anonymous">
0174 <title>Anonymous file</title>
0175 <para>
0176   This format is not intended to be used for normal data storage.  It is
0177   supported so that in case of a problem, you can supply the &kmymoney;
0178   development team with your file without disclosing any of the confidential
0179   details in your financial data.  For example, it changes institution, account,
0180   payee, and category names to strings such as "I000001" and "A000001", it makes
0181   similar changes to all data such as account numbers, and it also randomly
0182   changes the amounts of transactions.
0183 </para>
0185 <para>
0186   If instructed by the developers, use the <guimenuitem>Save as...</guimenuitem>
0187   menu item to store your data in anonymous format by selecting <literal
0188   role="filter">Anonymous files</literal> as the filter. This also changes the
0189   file extension to <filename class="extension">.anon.xml</filename>.
0190 </para>
0192 <para>
0193   To verify that your problem still exists, reload this anonymized
0194   file and try to duplicate your problem. If the problem is still
0195   present, send the file to the developer mailing list at &devlist;
0196   for further investigation. If the problem does not show ... well, I
0197   don't want to think about this scenario right now.
0198 </para>
0199 </sect1>
0200 </chapter>