1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
|
<?xml version="1.0" encoding="UTF-8"?>
<chapter id="details.formats">
<chapterinfo>
<authorgroup>
<author>
<firstname>Thomas</firstname>
<surname>Baumgart</surname>
<affiliation>
<address><email>[email protected]</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>
|
