You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
186 lines
7.2 KiB
186 lines
7.2 KiB
<?xml version="1.0" encoding="UTF-8"?>
|
|
<chapter id="details.formats">
|
|
<chapterinfo>
|
|
<authorgroup>
|
|
<author>
|
|
<firstname>Thomas</firstname>
|
|
<surname>Baumgart</surname>
|
|
<affiliation>
|
|
<address><email>ipwizard@users.sourceforge.net</email></address>
|
|
</affiliation>
|
|
</author>
|
|
</authorgroup>
|
|
<date>2009-05-08</date>
|
|
<releaseinfo>1.0</releaseinfo>
|
|
</chapterinfo>
|
|
|
|
<title>File Formats</title>
|
|
|
|
<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>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 <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-compressed file</title>
|
|
<para>
|
|
This is the normal format used by &kappname; when you store a file with the
|
|
extension <literal role="extension">.kmy</literal>.
|
|
</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 <literal role="extension">.gz</literal> (e.g.,
|
|
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-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 &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).
|
|
</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 in case of a problem as a method of supplying the &kappname;
|
|
development team with your file without disclosing any of your financial
|
|
data. If instructed by the developers, use the <guimenuitem>Save
|
|
as...</guimenuitem> menu item to store your data in anonymous format by
|
|
selecting <literal role="extension">.anon.xml</literal> as the file
|
|
extension. 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>
|
|
|