Specification of the Day Planner data format version 1
by Eskild Hustvedt
$Id: DPF_Spec 897 2006-11-02 14:03:22Z zero_dogg $
------------------------------------------------------

WARNING: THIS FORMAT IS DEPRECATED AND INSECURE. IT SHOULD NOT BE USED.

NOTE: DUE TO THE DEPRECIATED STATUS OF THIS FORMAT WE DO NOT ACCEPT
COMMENTS, ISSUES NOR FEEDBACK.

Index:
0 - Definitions
1 - Syntax
	1.1 Settings
	1.2 Comments
	1.3 Header
	1.4 Default settings
2 - Checksumming
3 - Contained data
4 - Encryption
5 - Comments, issues and feedback

0 - Definitions
---------------
Here are some definitions of words and phrases as used in this spec:

Numeric true/false: A value that can be either 0 (false) or 1 (true).

1 - Syntax
----------
The main syntax of the data file follows.

	1.1 Settings
	- - - - - - -
Settings are declared as "key = value" pairs. No quoting can be applied.
All key = value pairs can have an optional leading ";". You should include
spaces between the key, value and = like so:
	key = value
not like so:
	key=value
This due to better readability, it is however - not required.

	1.2 Comments
	- - - - - - -
All comments must be on their own line. The comment character is #,
all lines beginning with # will be skipped (except for the first line,
see section 1.3).

You can not include comments on the same line as settings. Example:
	key = value #this is not a valid comment

	1.3 Header
	- - - - -
The first line in a file following this specification should always look
like so:
# Content-type: text/x-dayplanner

This can be used to detect the file format.

	1.4 Default settings
	- - - - - - - - - - -
Here follows a list of all the mandatory settings in a DPD file:

DP_FormatVersion = 1
	The DPF version this file is
DP_Crypt = [Numeric true/false]
	If the contained data is encrypted or not
DP_DataMD5 = MD5_BASE64
	The BASE64 encoded MD5 sum of the contained data when decoded
ContainedData = BASE64 Encoded data
	The BASE64 encoded data outlined in section 3

2 - Checksumming
----------------
Each file must have a DP_DataMD5 setting. This is the MD5 BASE64 encoded checksum
of the *decoded* and *decrypted* data from ContainedData.
A program should refuse to import if this MD5 checksum doesn't match the checksum of
the decoded and decrypted data.

3 - Contained data
------------------
The contained data should be valid perl code (day planner eval();s the data).
This is the data contained within the ContainedData = setting. In the raw
data file it is encoded in base64.

The following variables are required:
$DP_OnlyBirthdays = [Numeric true/false];
	If the contained data /only/ contains birthdays.

The following variables are optional, but recommended:
$DP_ExportedBy = VERSION;
	The day planner version the data is exported by.
$DP_ExportedAt = UNIX TIME;
	The unix time the file was exported at.

When exported by a program other than day planner it is recommended that you set:
$DP_ExportedBySoft = "SOFTWARE NAME";
	The name of the software that exported it

You may add additional metadata there at will. It is recommended that any additional
metadata be written like so: $X_DP_NAME = BLAH;, meaning that this specification
favours additional metadata not specified here to be pefixed with an X_.

This version of the day planner data format supports these two data hashes:
	%MainCalendarContent
	%BirthdayCalendarContent
The format of the data hashes is outlined elsewhere in the document SaveformatSyntax.

It is recommended that if using Data::Dumper to dump the calendar content you
set the following settings:
	$Data::Dumper::Purity = 1;
	$Data::Dumper::Sortkeys = 0;
	$Data::Dumper::Indent = 0;

4 - Encryption
--------------
The data format natively supports encryption of the contained data.
The encryption used is blowfish (Crypt::Blowfish) as returned by Crypt::CBC.
The setting DP_Crypt must be 1 to indicate that the contained data is encrypted.
Otherwise a decryption will not be attempted. The decrypted data is checksummed
as normal as outlined in section 2.

5 - Comments, issues and feedback
---------------------------------
If you have any comments or feedback about this specification, or
have found some issues please contact the day planner developers.
Contact information can be found at http://home.gna.org/dayplanner/

You may also direct any questions to the same place.
